Page tree
Skip to end of metadata
Go to start of metadata
Your Rating: Results: 1 Star2 Star3 Star4 Star5 Star 85 rates

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
  • 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 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.

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))

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.