Configuration options defaults and documentation --> XSD

[borges]

Right now, we have:

• The allowed XML configuration options declared in the XSD;
• their default values effectivelly determined by hard coded values in Java code;
• options and default values documented in XML files used for the manual.

The problem with this setting is that it is cumbersome and time consuming to ensure that

1. all options defined in the XSD, have a documentation entry in the manual;
2. all default values listed in the manual match those in the Java code.

I propose moving all default values and all option documentation into the XSD itself. That would make it trivial to verify whether a given option lacks documentation and which is its default value.

This would obviously force us to generate the manual page from the XSD itself AND to take the default values from it, so it requires some work but long term maintenance would become a lot easier.

[ataylor]

I agree we should document in the xsd's and then generate a manual page from it.

Im not sure about the defaults tho, there are places in the code where we use these for things other than the actual configuration objects, i.e.

if (ConfigurationImpl.DEFAULT_CLUSTER_USER.equals(configuration.getClusterUser()) && ConfigurationImpl.DEFAULT_CLUSTER_PASSWORD.equals(configuration.getClusterPassword()))

and also in some default constructors. we would have to find away to address this as well

[jbertram]

I think this is a great idea, and I'd like to take it a step farther if possible.  I'd like to add extensive documentation to the schema itself via <xs:documentation>.  Perhaps then we can generate the configuration-index.xml chapter from the XSD.

[borges]

A Java source full of static final values could be generated from the xsd. If the default values are not present in the XSD we can't generated the whole manual entries from it.

[ataylor]

sounds like a plan, lets raise a jira for it