Best way to keep Documentation for a XML Configuration file?

Question

I have a xml configuration file for an application and i am wondering which is the best way to keep documentation for it. IE Possible tags, values, etc

Is there a tool, or schema standard or practice that i should follow?

Answer 1

If your XML file conforms to a schema or a DTD, then this schema or DTD would be a good place to put your documentation. Otherwise, you can supply samples.

Answer 2

A lot of people use XML comments (<!-- ... -->) for this.

Answer 3

If you have rolled your own custom config XML format then just generate your own schema for it and document it in there.

Answer 4

Something which I've never seen anywhere else but which might make sense: Use a <comment> element and in your parser, ignore anything inside of it. This would allow to have copy'n'paste ready examples in the config file plus you could nest them to explain various points in each example.

Answer 5

I believe that Aaron Digulla's answer (XML comments) is the simplest. Otherwise, two solutions:

1. If you control the schema, add a <comment> element (Docbook, for instance, does it).

2. If you don't, create a namespace like http://www.example.org/mynamespaces/doc and put <comment> elements in the file, prefixed by this namespace, for instance <doc:comment> (this assumes that your XML validation systme will ignore elements in unknown namespaces, as, for instance, NVDL permits).