[infinispan-dev] Configuration reference generation - rework

[Sanne Grinovero]

2010/9/14 Manik Surtani <manik at jboss.org>:
>
> 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_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
>

while you're thinking about this, you might also find a solution to
not depend on com.sun.* packages to generate the documentation. Of
course I won't say that this is a priority, but while you're at it if
you happen to see a cool alternative that would be nice. More info
soon on an appropriate thread.

Cheers,
Sanne