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():
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:
In this case, we'd be looking at the <invocationbatching ...> element:
These docs are generated from notes made on the JAXB beans annotated with custom @configRef Javadoc annotations:
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@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/infinispan-dev
--
Manik Surtani
Lead, Infinispan
Lead, JBoss Cache