You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Carsten Ziegeler <cz...@s-und-n.de> on 2004/04/29 14:44:29 UTC
[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/
RE: [RT] Generating docs and entries for sitemap component from JavaDocs
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
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
Posted by Sylvain Wallez <sy...@apache.org>.
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
Posted by Joerg Heinicke <jo...@gmx.de>.
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
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
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
Posted by Sylvain Wallez <sy...@apache.org>.
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
Posted by Christian Haul <ha...@informatik.tu-darmstadt.de>.
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
Posted by Nicola Ken Barozzi <ni...@apache.org>.
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 nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
RE: [RT] Generating docs and entries for sitemap component from JavaDocs
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
> -----Original Message-----
> From: news [mailto:news@sea.gmane.org] On Behalf Of Nicola Ken Barozzi
> Sent: Thursday, April 29, 2004 5:09 PM
> To: dev@cocoon.apache.org
> 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:8888/)
>
> 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
Posted by Nicola Ken Barozzi <ni...@apache.org>.
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:8888/)
I know, one step at a time, but in any case I'm dropping you this note. :-)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [RT] Generating docs and entries for sitemap component from JavaDocs
Posted by Bertrand Delacretaz <bd...@apache.org>.
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
<section name="parameters">
...
<section name="sitemap-example">
Then, a narrative XML document which completes this reference doc could
use elements like
<include-doc-section name="parameters"/>
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
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
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
Posted by Tony Collen <co...@umn.edu>.
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
Posted by Guido Casper <gc...@s-und-n.de>.
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. 5 mailto:gcasper@s-und-n.de
D-33100 Paderborn http://www.s-und-n.de
-------------------------------------------------
RE: [RT] Generating docs and entries for sitemap component from JavaDocs
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
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:vadim@reverycodes.com]
> Sent: Monday, May 03, 2004 3:49 PM
> To: dev@cocoon.apache.org
> 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
Posted by Vadim Gritsenko <va...@reverycodes.com>.
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
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
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/