GREYDiscussion points on implementing c2b specific documentation.GREY
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
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
A javadoc doclet would probably be feasible, but as far as Igreg 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.
- 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))
Check out the ant build file:
Then from the root of the project you want to generate c2b documentation for:
The generation html files should end up in