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

[Vladimir Blagojevic]

On 7/9/09 11:58 AM, Manik Surtani wrote:
>
> 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.
Exactly!

Jason, I am almost done with xml configuration reading based on 
combination of reflection and annotations of configuration (the nutshell 
is like 100 lines of code). We already create human readable 
configuration reference from the same source. And now on top of it if we 
can create, and I think we can, xsd schema along with xsd documentation 
tags that come from the same annotations then that would be an 
achievement worth at least one blog entry and one round of beers on 
Manik!!! Maintenance cost of Infinispan configuration converging to 
zero! No bull!

Cheers