Re: [infinispan-dev] Configuration reference generation - rework

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_invoc... 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: -- Manik Surtani manik(a)jboss.org Lead, Infinispan Lead, JBoss Cache http://www.infinispan.org http://www.jbosscache.org