On 9 Jul 2009, at 12:06, Vladimir Blagojevic wrote:
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!
I get the feeling you're kinda excited about this, Vladimir... ! :-)
Cheers
--
Manik Surtani
manik(a)jboss.org
Lead, Infinispan
Lead, JBoss Cache
http://www.infinispan.org
http://www.jbosscache.org