cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sylvain Wallez <sylv...@apache.org>
Subject Re: [RT] Generating docs and entries for sitemap component from JavaDocs
Date Mon, 03 May 2004 16:53:59 GMT
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 }


Mime
View raw message