 | Draft for 4.0 Draft for 4.0 - prototype is in svn, +/- working, needs refinement - currently a manual procedure, not integrated in maven build. See MAGNOLIA-2491@jira. |
We have more and more components which are configured through content2bean. It seems it would be fairly easy to generate documentation for these.
Shortcomings of javadoc
- too many unrelated (ie non configurable) classes
- too much unrelated information
- programmer-oriented
Advantages of c2b specific documentation
- could be described in terms of paths, nodes, properties.
- could be graphic, examples could be generated.
- one single place for all Magnolia configurable elements
- could still be linked to javadoc
Implementation
A javadoc doclet would probably be feasible, but as far as I[greg] am concerned, the simplest way would be to implement an xdoclet2 plugin.
Classes that need to be included in the doc could have a @c2b tag for instance.
http://svn.magnolia-cms.com/svn/build/content2bean-xdoclet-plugin/trunk/
Open questions
- how do we discover implementations (do we want to)
- where do we deploy the generated doc
- how do we link to javadoc (we have aggregated javadoc for all ce for instance, but not for ee) - maybe a simple configuration mapping packages to javadoc URLs would work
- do we include this in the maven site generation ? (ultimately yes, but this might not be a high priority, as it might not be trivial atm, esp. since xdoclet2 currently provides a maven plugin - it is generally used to generate code or resources rather than docu - but not a maven report)
- how do we document/represent classes that are configured with specific transformers - and how should this tool know about this ? should we have extra tags that "link" to these transformers ? (in which case we might want to look into using annotations instead of the current mechanisms we have at the moment - and then i'm not sure how xdoclet supports annotations (as opposed to javadoc tags))
Links
http://xdoclet.codehaus.org/ http://xdoclet.codehaus.org/Your+own+plugin http://docs.codehaus.org/display/MAVENUSER/Write+your+own+report+plugin
Usage
Check out the ant build file:
cd /some/place svn co http://svn.magnolia-cms.com/svn/build/content2bean-xdoclet-plugin/trunk/c2b-docgen.xml
Then from the root of the project you want to generate c2b documentation for:
export ANT_OPTS="-Xms64M -Xmx512M" ant -f /some/place/c2b-docgen.xml
The generation html files should end up in target/c2b-docgen.