[infinispan-dev] Configuration reference generation - rework

[Manik Surtani]

Essentially the crux of the problem is that we currently use the Configuration bean for programmatic configuration.  Setters are Javadoc'd accordingly.  E.g., this setter enables invocation batching and is Javadocced accordingly.

Configuration#setInvocationBatching():

http://pastie.org/1157879

Now this makes use of an internal component to actually hold the value.  It is done this way so that the JAXB schema generator and parser can handle properly formatted XML equivalents.

The ConfigDoc stuff that Vladimir wrote earlier grabs additional docs from these internal components to generate the XML config reference guide:

http://docs.jboss.org/infinispan/4.1/apidocs/config.html

In this case, we'd be looking at the <invocationbatching ...> element:

http://docs.jboss.org/infinispan/4.1/apidocs/config.html#ce_default_invocationBatching

These docs are generated from notes made on the JAXB beans annotated with custom @configRef Javadoc annotations:

http://pastie.org/1157880

The problem here is that we are repeating ourselves.  And that leads to poor and inconsistent documentation at first, and completely unmaintained documentation as time goes on.  :)

So my proposal is as such:

* We document setters on Configuration and GlobalConfiguration *really* well.
* We reference these setters from internal components such as Configuration.InvocationBatching.setEnabled() using annotations.  E.g., http://pastie.org/1157888
* When generating config docs, we have a reference to the actual setter thanks to this annotation, and can use it to grab the "real" Javadocs for this setting and add it to the XML config reference.

WDYT?

Cheers
Manik



On 14 Sep 2010, at 11:51, Vladimir Blagojevic wrote:

> Hey all,
> 
> Manik and I talked privately regarding this topic through https://jira.jboss.org/browse/ISPN-626 and we concluded that we could use some input from people that have used configuration reference markers within Infinispan code etc. Manik basically had a few ideas where he wanted to polish/expand the final look of configuration reference (summed up in ISPN-626) and upon closer inspection I think that we need to rework configuration markers to make things simpler and easier to use.
> 
> One of the things I wanted to do is replace javadoc tag @configRef with annotation(s) and use pure comment text of javadoc elements as input for both javadoc and configuration reference. So lets gather some more ideas, and I'll work on this on a side whenever I need the break from hard core stuff :)
> 
> Cheers,
> Vladimir
> 
> 
> --
> Vladimir Blagojevic
> JBoss Clustering Team
> JBoss, by Red Hat
> 
> 
> 
> 
> _______________________________________________
> infinispan-dev mailing list
> infinispan-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/infinispan-dev

--
Manik Surtani
manik at jboss.org
Lead, Infinispan
Lead, JBoss Cache
http://www.infinispan.org
http://www.jbosscache.org




-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/infinispan-dev/attachments/20100914/c90a6f2f/attachment.html