okay
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 XYZ.java
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, @author
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 pipeline:
<map:pipeline>
<map:match pattern="reference-doc/*">
<map:aggregate>
<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:aggregate>
<map:transform src="stylesheets/reference-doc2document.xsl"/>
<map:serialize>
</map:match>
<map:match pattern="javadoc-{1}"/>
<map:generator type="javadoc" src="src/java/...../{1}.java"/>
<map:serialize/>
</map:match>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
