I don't want to sound like a broken record, but IMO this style of docs
belongs in the schema file in xsd:documentation tags. Then IDEA and
Eclipse display the docs while you are actually editing the config file.
You could then use one of the many tools out there to generate docs, or
extend one to produce it in a more docbook-like way.
For the config API, just use javadoc, you can then describe things in a
way more specific to the API.
Manik Surtani wrote:
Interesting discussions.
I agree that JAXB *would* have been the ideal way about this, but that
brings in a) additional deps with Java5, and b) a not-so-pretty object
model for configuration beans, and c) does not help us generate docs.
So essentially we have:
1) a simple(-ish) object model for programmatic configuration.
2) an XML parser to parse a coherent XML file and generate the beans in
(1).
3) documentation for all setters in (1) and all elements/attributes in (2).
As Vladimir pointed out, this effort is to remove the hand-written
parser we have which handles (2), and to save us writing hand-written
docs for (3). By annotating the object model in (1), we can generate
appropriate documentation for (3) as well as parse XML to populate the
bean for (2).
Emmanuel, note that these annotations are internal only and are not
public API. End users would configure stuff by doing:
Configuration c = new Configuration();
c.setBlah( blah );
The annotations are purely for core devs who would need to add a new
configuration element for new feature X. By adding a new getter and
setter to the Configuration bean, and appropriately annotating it, this
new config element is automagically added to the XSD, will be parsed
from XML, and is documented.
That said, I do like the "fluent config" approach where folks can do:
c.setBlah( blah ).setFoo( foo );
HTH,
Cheers
Manik
On 22 Jun 2009, at 18:41, Vladimir Blagojevic wrote:
> On 6/22/09 10:52 AM, Emmanuel Bernard wrote:
>> OK here is my take.
>>
>> Populating bean is fairly PITA for a user and a fluent API approach
>> makes configuration more readable.
> Fluent config API is the one that allows chaining calls, right? These
> are very elegant, but they seem more suitable for configs that follow
> more of a grammar like structure. Infinispan's config tree is not so
> nice so to speak.
>>
>>
http://anonsvn.jboss.org/repos/hibernate/search/trunk/src/test/java/org/h...
>>
>> (check NotUseddefineMapping)
>> and the root class
>>
http://anonsvn.jboss.org/repos/hibernate/search/trunk/src/main/java/org/h...
>>
>>
>> if you want to stay on the bean side, I am wondering why you don't
>> use JAXB or something like that to bind the XML model to the object
>> model.
>
> We want to reuse these annotations to kill three birds with one stone.
> Configuration beans are the source, or if you want - code is the
> source. We annotate those beans and get for free human readable
> configuration documentation, configuration schema, and, if possible,
> use those annotations in conjunction with beans to populate the beans
> automatically during configuration reading from xml.
>
> Does it make better sense now? Appreciate your input!
>
> Regards,
> Vladimir
> _______________________________________________
> 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
--
Jason T. Greene
JBoss, a division of Red Hat