cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tony Collen <colle...@umn.edu>
Subject Re: [RT] Generating docs and entries for sitemap component from JavaDocs
Date Thu, 29 Apr 2004 14:32:58 GMT
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

Mime
View raw message