cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bernhard Huber <>
Subject Re: Documentation Format... (user reference pages scenario)
Date Thu, 21 Nov 2002 22:29:33 GMT
> 1) Add at least the following javadoc tags to the java source code of 
> existing components:
> - @cocoon:name [1]
> - @cocoon:status [1]
> - All "configuration tags" from [1]
> - All "setup tags" from [1]
> - A "short user-level description" tag?
> - A "component category" tag? (Generator, Transformer, etc.)
> 2) Supplement this info with an xxx-manpage.xml file (or whatever, but need a 
> standard name) in xdocs format, that can contain usage examples and 
> additional information, similar in concept to package.html for java packages.
> This is stored in the same directory as the component and xxx is the same as 
> the java class name ("FileGenerator-manpage.xml").
> An empty xxx-manpage.xml causes only the content of the javadoc tags 
> to be published, but the file is required to decide which components are 
> included in the user reference docs. We don't want a user reference page for 
> every java class in the source code tree.
> 3) Implement a Cocoon/Forrest pipeline to publish user reference pages from 
> these tags and XML doc files. 
> As I understand Bernhard has this covered, but I don't know the details. If 
> we can get these javadoc tags in XML form in a pipeline, it would be easy to 
> merge them with the xxx-manpage.xml file.
I'd like to give a solution, and refinement to your ideas:

1. Input-data from java files
1.1 first sentence of javadoc ( ie. /** First sentence. .... */ class XY 
... )

1.2 general tags having prefix of @cocoon, limited to the class 
documentation: @cocoon:name, @cocoon:status

1.3 general javadoc tags in the class documentation: @version, @since, 

1.4 whole javadoc comment, of classdoc, (need to pass it to jtidy, to 
transform it xhtml)

Note: I am not quite sure where we should allow writing @cocoon tags. 
You may write it at classlevel, memberlevel, or methodlevel.

2. Input-date from XYZ-manpage.xml, or XYZ-merging.xml
Seperated xml document, describing the component more literally.

Thus assuming we have a javadoc generator, we might define following 
   <map:match pattern="reference-doc/*">
       <map:part src="cocoon:/javadoc-{1}"/>
       <!-- need to figure out how get the real dir-value of .... -->
       <map:part src="src/java/...../{1}-manpage.xml"/>
     <map:transform src="stylesheets/reference-doc2document.xsl"/>

   <map:match pattern="javadoc-{1}"/>
     <map:generator type="javadoc" src="src/java/...../{1}.java"/>

   The imaginative javadoc generator will use qdox, xdoclet, javadoc 
doclet, to generate xml from the original java source file.

What do you think?
Does anyone know if there is alread a java to xml tool available, or a 
java DTD, or at least a javadoc DTD?

regards bernhard

View raw message