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
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.
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.
sounds like a plan, lets raise a jira for it