On 8 Jul 2009, at 19:46, Jason T. Greene wrote:
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.
+1 to putting this information in the XSD in documentation tags, but
this should be done by the XSD generation tool based on annotated
info. I just think that if docs are in two separate places, they are
not going to get maintained in the long run and will degenerate.
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
--
Manik Surtani
manik(a)jboss.org
Lead, Infinispan
Lead, JBoss Cache
http://www.infinispan.org
http://www.jbosscache.org