RE: [RT] Generating docs and entries for sitemap component from JavaDocs
Sylvain Wallez wrote: > >The general idea is to use some javadoc tags, like > @cocoon.something to > >specify sitemap components (their name, perhaps the logger category > >etc.) and generate the sitemap entries from this. > >In addition the JavaDoc for the class will be converted into the XML > >doc file for that component (and added to the index etc.) > > > > > > I'm ok with this approach for *reference* documentation, as > this effort often has to be duplicated between the javadoc > and the xdocs. But this isn't IMO suitable for introductory > material, which needs to be more verbose that what we can > reasonably put in a Java file, and because of the > hierarchical/alphabetical navigation structure docs extracted > from code will produce. > Sure, yes, I wasn't wery clear in my mail: I only want to generate reference docs - nothing more. Carsten
RE: [RT] Generating docs and entries for sitemap component from JavaDocs
Sylvain Wallez wrote: > Joerg Heinicke wrote: > > > On 03.05.2004 18:53, Sylvain Wallez wrote: > > > >> Question : why do we need to add components from blocks in > the main > >> sitemap? We could just declare them in their respective samples > >> sitemap... > > > > > > Other blocks can not use these components. These blocks > would need to > > get the component declarations from their "home" blocks. > > > What they need is the corresponding class files. So as long > as these classes are in WEB-INF/lib, they can declare the > needed components in their own sitemap also. Or am I missing > something? > Sure that would work. But we are adding sitemap components from blocks to the main sitemap since we have blocks (fop etc.) and imho it makes sense as these are general purpose components. It might not make sense for special components like the portal generator. But we can fine tune this of course somehow. Carsten
Re: [RT] Generating docs and entries for sitemap component from JavaDocs
Joerg Heinicke wrote:
On 03.05.2004 18:53, Sylvain Wallez wrote:
Question : why do we need to add components from blocks in the main
sitemap? We could just declare them in their respective samples
sitemap...
Other blocks can not use these components. These blocks would need to
get the component declarations from their "home" blocks.
What they need is the corresponding class files. So as long as these
classes are in WEB-INF/lib, they can declare the needed components in
their own sitemap also. Or am I missing something?
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Re: [RT] Generating docs and entries for sitemap component from JavaDocs
On 03.05.2004 18:53, Sylvain Wallez wrote: Question : why do we need to add components from blocks in the main sitemap? We could just declare them in their respective samples sitemap... Other blocks can not use these components. These blocks would need to get the component declarations from their "home" blocks. Joerg
Re: [RT] Generating docs and entries for sitemap component from JavaDocs
Late answer, but hey, better than nothing!
Carsten Ziegeler wrote:
I think we discussed this and I think to remember that the
general opinion has been pro the following.
I think we should start generating the user docs for sitemap
components from the java docs. Currently these are separate
things which leads to
- user doc is not updated when the component changes
- component is only documented in java docs
- duplicate comments
In addition I would like to generate the entries for the sitemap
from the javadocs as well. Currently we have the core components
already in the main sitemap and add the optional components (from
blocks) by using the xpatch utility. So again, this is an
addition configuration file.
Question : why do we need to add components from blocks in the main
sitemap? We could just declare them in their respective samples sitemap...
The general idea is to use some javadoc tags, like @cocoon.something
to specify sitemap components (their name, perhaps the logger
category etc.) and generate the sitemap entries from this.
In addition the JavaDoc for the class will be converted into the
XML doc file for that component (and added to the index etc.)
I'm ok with this approach for *reference* documentation, as this effort
often has to be duplicated between the javadoc and the xdocs. But this
isn't IMO suitable for introductory material, which needs to be more
verbose that what we can reasonably put in a Java file, and because of
the hierarchical/alphabetical navigation structure docs extracted from
code will produce.
I'm currently in "do mood" and played a little bit with a qdox
based ant task and would like to get a first version finished in
the next days. The first version will be used for those
components that currently don't have docs, so (nothing) will
break and we can play around with it.
Well, JFDI!
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
RE: [RT] Generating docs and entries for sitemap component from JavaDocs
Oh my, thanks for reporting, Vadim. The tool can now generate docs for components contained in blocks, but as blocks don't have docs right now, there is no hook in the build system for generating the docs :( I have just committed I small patch for it, so it should work now. Anyway, I think we should test a little bit with everything and perhaps disable the generation for the 2.1.5 release. Carsten > -Original Message- > From: Vadim Gritsenko [mailto:[EMAIL PROTECTED] > Sent: Monday, May 03, 2004 3:49 PM > To: [EMAIL PROTECTED] > Subject: Re: [RT] Generating docs and entries for sitemap > component from JavaDocs > > Carsten Ziegeler wrote: > > >Have a look, comment and - most important - improve it! > > > > > > BUILD FAILED > C:\cocoon-2.1\tools\targets\webapp-build.xml:93: Following > error occured while executing this line > C:\cocoon-2.1\build\cocoon-2.1.5-dev\temp\blocks-build.xml:120 > 0: DocDir > (C:\cocoon-2.1\build\cocoon-2.1.5-dev\documentation\xdocs\user > docs) is not a directory. > > > With local.build.properties: > > exclude.webapp.documentation=true > exclude.webapp.javadocs=true > > exclude.documentation=true > exclude.javadocs=true > > exclude.validate.xdocs=true > exclude.validate.jars=true > > > Vadim >
Re: [RT] Generating docs and entries for sitemap component from JavaDocs
Carsten Ziegeler wrote: Have a look, comment and - most important - improve it! BUILD FAILED C:\cocoon-2.1\tools\targets\webapp-build.xml:93: Following error occured while executing this line C:\cocoon-2.1\build\cocoon-2.1.5-dev\temp\blocks-build.xml:1200: DocDir (C:\cocoon-2.1\build\cocoon-2.1.5-dev\documentation\xdocs\userdocs) is not a directory. With local.build.properties: exclude.webapp.documentation=true exclude.webapp.javadocs=true exclude.documentation=true exclude.javadocs=true exclude.validate.xdocs=true exclude.validate.jars=true Vadim
RE: [RT] Generating docs and entries for sitemap component from JavaDocs
I just finished the first version of the documentation task. It generates documentation and sitemap entries from some java doc tags and merges the existing documentation into the generated one. In addition it takes some information out of the Java Source, like if the class implements logging etc. You can have a look at two samples: the file generator and the html serializer. The task itself is a quick written one, so the code is not cleaned up but should do the work :) Have a look, comment and - most important - improve it! (Nothing is carved in stone right now, so we can of course discuss the names of the tags, which tags make sense etc. It's just a starting point.) Carsten Carsten Ziegeler Open Source Group, S&N AG http://www.osoco.net/weblogs/rael/
Re: [RT] Generating docs and entries for sitemap component from JavaDocs
Carsten Ziegeler wrote: ... I think we should just start with something (even if we throw it away later on) and improve it. +1 Since many projects using Forrest use or are planning to use javadoc tags to generate documentation, I was musing about doing it in the future in Forrest, so I'm going to happily watch your efforts and see what can be done later on to generalize it and bring it in Forrest. :-) -- Nicola Ken Barozzi [EMAIL PROTECTED] - verba volant, scripta manent - (discussions get forgotten, just code remains) -
Re: [RT] Generating docs and entries for sitemap component from JavaDocs
Carsten Ziegeler wrote: Tony Collen wrote: As I said, I'm leery of embedding a bunch of user-guide type material into the Javadocs, but I would be more comfortable if it was used as more of a technical reference than anything. Maybe a quick one or two-paragraph description of how the component works or what it does, and a description of any parameters that it might take. Beyond that, I think we should still use the external documentation format. That isn't to say, however, that we couldn't generate a large technical reference doc from these, and include them with the "regular" docs. Basically I mostly agree with you. It's not that good to have user docs in the Java Source, but it's better to have the JavaDocs as a documentation than nothing :) (which is today the case - sometimes at least). While I understand the reservation against userdocs from sources I believe it is currently the best option we have unless we can muster a substantial doc writing effort. I just would like to point to the neglected package.html files that should be used as introduction / overview to a java package. Using both could give better docs and help keeping it organized and maintained. However, having additional tutorials and introductions is certainly desirable. But I'm afraid that required different skills and is probably hard to do incrementally or in the passing while modifying code. just my 2¢ Chris.
RE: [RT] Generating docs and entries for sitemap component from JavaDocs
> -Original Message-
> From: news [mailto:[EMAIL PROTECTED] On Behalf Of Nicola Ken Barozzi
> Sent: Thursday, April 29, 2004 5:09 PM
> To: [EMAIL PROTECTED]
> Subject: Re: [RT] Generating docs and entries for sitemap
> component from JavaDocs
>
> Bertrand Delacretaz wrote:
> ...
> > Yes, *do* is the key here.
> > Go, Carsten, go!
>
> Hint1: it would be cool if we could put these in Forrest.
>
> Hint2: Why not use the qdox generator that comes in its block?
> This could make the docs be integrated with Forrest docs,
> and one doesn't need to generate them all to see them
> ('forrest run'->http://localhost:/)
>
> I know, one step at a time, but in any case I'm dropping you
> this note. :-)
>
Yes, thanks! To be honest, I'm happy for every comment.
First thought I had was to use the qdox source, but this would
require that you have access to the source files when the docs
are accessed. I think adding all source files to the webapp
isn't that good. So perhaps only adding the required ones might
make sense. Let's see.
I think we should just start with something (even if we throw
it away later on) and improve it.
Carsten
Re: [RT] Generating docs and entries for sitemap component from JavaDocs
Bertrand Delacretaz wrote:
...
Yes, *do* is the key here.
Go, Carsten, go!
Hint1: it would be cool if we could put these in Forrest.
Hint2: Why not use the qdox generator that comes in its block?
This could make the docs be integrated with Forrest docs,
and one doesn't need to generate them all to see them
('forrest run'->http://localhost:/)
I know, one step at a time, but in any case I'm dropping you this note. :-)
--
Nicola Ken Barozzi [EMAIL PROTECTED]
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
-
Re: [RT] Generating docs and entries for sitemap component from JavaDocs
Le 29 avr. 04, à 16:57, Carsten Ziegeler a écrit : ...Basically I mostly agree with you. It's not that good to have user docs in the Java Source, but it's better to have the JavaDocs as a documentation than nothing :) (which is today the case - sometimes at least). Big +1 And Carsten said he was in a "do mood" today so let's try not to slow him down ;-) ...The first step would be a task that does: FileGenerator.java -> userdocs/generators/file.xml (based on the info in the class) Sounds good. And if you could find a way (intermediate document?) to put "hooks" into the generated document, it might be easier later on to merge them with narrative documentation. For example: @cocoondoc-section parameters @cocoondoc-... (tags describing parameters) @cocoondoc-section sitemap-example @cocoondoc-... (tags describing sitemap example) Which could translate in the XML generated docs to ... Then, a narrative XML document which completes this reference doc could use elements like to easily merge both things. ...But I think, let's do simple steps :) Yes, *do* is the key here. Go, Carsten, go! -Bertrand
RE: [RT] Generating docs and entries for sitemap component from JavaDocs
Tony Collen wrote: > > Carsten Ziegeler wrote: > > > I think we discussed this and I think to remember that the general > > opinion has been pro the following. > > > > I think we should start generating the user docs for sitemap > > components from the java docs. Currently these are separate things > > which leads to > > Hmm... I'm not sure if I like the idea of having the userdocs > embedded in the source code. > > > - user doc is not updated when the component changes > > Are the Javadocs even updated then the component changes? > > > - component is only documented in java docs > > If we embed the user docs, this only becomes worse, IMO, > since the single source of the docs would be the from the > comment tags. I see how the other docs would be generated > from the source, but it's just not sitting right with me. > > Unless we use this purely as a component technical reference, > where there would be some sparse information (i.e. what > parameters we can pass to it), then I would feel a better > towards this idea. > > > - duplicate comments > > Where? > > > In addition I would like to generate the entries for the > sitemap from > > the javadocs as well. Currently we have the core components > already in > > the main sitemap and add the optional components (from > > blocks) by using the xpatch utility. So again, this is an addition > > configuration file. > > > > The general idea is to use some javadoc tags, like > @cocoon.something > > to specify sitemap components (their name, perhaps the > logger category > > etc.) and generate the sitemap entries from this. > > In addition the JavaDoc for the class will be converted > into the XML > > doc file for that component (and added to the index etc.) > > I'm generally +1 on this. > > > I'm currently in "do mood" and played a little bit with a > qdox based > > ant task and would like to get a first version finished in the next > > days. The first version will be used for those components that > > currently don't have docs, so (nothing) will break and we can play > > around with it. > > > > WDYT? > > As I said, I'm leery of embedding a bunch of user-guide type > material into the Javadocs, but I would be more comfortable > if it was used as more of a technical reference than > anything. Maybe a quick one or two-paragraph description of > how the component works or what it does, and a description of > any parameters that it might take. Beyond that, I think we > should still use the external documentation format. > > Possible tags: > @cocoon.component.loglevel (one) > @cocoon.component.sitemapname (one) > @cocoon.component.description (one) > @cocoon.component.parameter (multiple) > > That isn't to say, however, that we couldn't generate a large > technical reference doc from these, and include them with the > "regular" docs. > Basically I mostly agree with you. It's not that good to have user docs in the Java Source, but it's better to have the JavaDocs as a documentation than nothing :) (which is today the case - sometimes at least). In general, if you have two places to document a single thing than there are always problems with updating both places. Either one is lazy or simple forgets about it etc. The JavaDoc for a sitemap component usually contains a general description and the configuration possibilities, so this can go into the user docs. The first step would be a task that does: FileGenerator.java -> userdocs/generators/file.xml (based on the info in the class) So basically we generate a reference for sitemap components with the task. The Cocoon user docs of course still contain much more info than the reference provides, so it's just an additional information. As a second step I'm thinking of merging two sources, which means you write a nice user docs in the xml format and the build system adds all the infos from the JavaSource, like configuration etc. But I think, let's do simple steps :) Carsten
Re: [RT] Generating docs and entries for sitemap component from JavaDocs
Carsten Ziegeler wrote: I think we discussed this and I think to remember that the general opinion has been pro the following. I think we should start generating the user docs for sitemap components from the java docs. Currently these are separate things which leads to Hmm... I'm not sure if I like the idea of having the userdocs embedded in the source code. - user doc is not updated when the component changes Are the Javadocs even updated then the component changes? - component is only documented in java docs If we embed the user docs, this only becomes worse, IMO, since the single source of the docs would be the from the comment tags. I see how the other docs would be generated from the source, but it's just not sitting right with me. Unless we use this purely as a component technical reference, where there would be some sparse information (i.e. what parameters we can pass to it), then I would feel a better towards this idea. - duplicate comments Where? In addition I would like to generate the entries for the sitemap from the javadocs as well. Currently we have the core components already in the main sitemap and add the optional components (from blocks) by using the xpatch utility. So again, this is an addition configuration file. The general idea is to use some javadoc tags, like @cocoon.something to specify sitemap components (their name, perhaps the logger category etc.) and generate the sitemap entries from this. In addition the JavaDoc for the class will be converted into the XML doc file for that component (and added to the index etc.) I'm generally +1 on this. I'm currently in "do mood" and played a little bit with a qdox based ant task and would like to get a first version finished in the next days. The first version will be used for those components that currently don't have docs, so (nothing) will break and we can play around with it. WDYT? As I said, I'm leery of embedding a bunch of user-guide type material into the Javadocs, but I would be more comfortable if it was used as more of a technical reference than anything. Maybe a quick one or two-paragraph description of how the component works or what it does, and a description of any parameters that it might take. Beyond that, I think we should still use the external documentation format. Possible tags: @cocoon.component.loglevel (one) @cocoon.component.sitemapname (one) @cocoon.component.description (one) @cocoon.component.parameter (multiple) That isn't to say, however, that we couldn't generate a large technical reference doc from these, and include them with the "regular" docs. Carsten Regards, Tony
Re: [RT] Generating docs and entries for sitemap component from JavaDocs
Carsten Ziegeler wrote: The general idea is to use some javadoc tags, like @cocoon.something to specify sitemap components (their name, perhaps the logger category etc.) and generate the sitemap entries from this. In addition the JavaDoc for the class will be converted into the XML doc file for that component (and added to the index etc.) +1 for both. Guido -- Guido Casper - S&N AG, Competence Center Open Source Tel.: +49-5251-1581-87 Klingenderstr. 5mailto:[EMAIL PROTECTED] D-33100 Paderborn http://www.s-und-n.de -
[RT] Generating docs and entries for sitemap component from JavaDocs
I think we discussed this and I think to remember that the general opinion has been pro the following. I think we should start generating the user docs for sitemap components from the java docs. Currently these are separate things which leads to - user doc is not updated when the component changes - component is only documented in java docs - duplicate comments In addition I would like to generate the entries for the sitemap from the javadocs as well. Currently we have the core components already in the main sitemap and add the optional components (from blocks) by using the xpatch utility. So again, this is an addition configuration file. The general idea is to use some javadoc tags, like @cocoon.something to specify sitemap components (their name, perhaps the logger category etc.) and generate the sitemap entries from this. In addition the JavaDoc for the class will be converted into the XML doc file for that component (and added to the index etc.) I'm currently in "do mood" and played a little bit with a qdox based ant task and would like to get a first version finished in the next days. The first version will be used for those components that currently don't have docs, so (nothing) will break and we can play around with it. WDYT? Carsten Carsten Ziegeler Open Source Group, S&N AG http://www.osoco.net/weblogs/rael/
