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(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/infinispan-dev

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

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 >> >> >> -- >> Vladimir Blagojevic >> JBoss Clustering Team >> JBoss, by Red Hat >> >> >> >> >> _______________________________________________ >> infinispan-dev mailing list >> infinispan-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/infinispan-dev > > -- > Manik Surtani > manik(a)jboss.org > Lead, Infinispan > Lead, JBoss Cache > http://www.infinispan.org > http://www.jbosscache.org > > > > > _______________________________________________ > infinispan-dev mailing list > infinispan-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/infinispan-dev -- Vladimir Blagojevic JBoss Clustering Team JBoss, by Red Hat _______________________________________________ infinispan-dev mailing list infinispan-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/infinispan-dev

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 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 >> >> >> -- >> Vladimir Blagojevic >> JBoss Clustering Team >> JBoss, by Red Hat >> >> >> >> >> _______________________________________________ >> infinispan-dev mailing list >> infinispan-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/infinispan-dev > > -- > Manik Surtani > manik(a)jboss.org > Lead, Infinispan > Lead, JBoss Cache > http://www.infinispan.org > http://www.jbosscache.org > > > > > _______________________________________________ > infinispan-dev mailing list > infinispan-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/infinispan-dev -- Vladimir Blagojevic JBoss Clustering Team JBoss, by Red Hat _______________________________________________ infinispan-dev mailing list infinispan-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/infinispan-dev