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

On 14 Sep 2010, at 12:39, Vladimir Blagojevic wrote: Yeah perfect. I would just call your ProgrammaticSetter a ConfigurationReference. We also need to add "name" annotation field just as we had it in @configRef. A couple of annotation fields in ConfigurationReference annotation should be able to handle all these cases of naming elements, direct comments insertion or picking comments up from somewhere else etc etc Sure. Cheers, Vladimir On 2010-09-14, at 1:04 PM, Manik Surtani wrote: 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: 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