[infinispan-dev] Re: property tags in configuration files

[Jason T. Greene]

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/hibernate/search/test/configuration/ProgrammaticMappingTest.java 
>>>
>>> (check NotUseddefineMapping)
>>> and the root class
>>> http://anonsvn.jboss.org/repos/hibernate/search/trunk/src/main/java/org/hibernate/search/cfg/SearchMapping.java 
>>>
>>>
>>> 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 at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
> 
> -- 
> Manik Surtani
> manik at jboss.org
> Lead, Infinispan
> Lead, JBoss Cache
> http://www.infinispan.org
> http://www.jbosscache.org
> 
> 
> 
> 
> _______________________________________________
> infinispan-dev mailing list
> infinispan-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/infinispan-dev


-- 
Jason T. Greene
JBoss, a division of Red Hat