It is a good thing to facilitate documentation within the configuration model it self. At the moment users can use XML comments. But when synapse configuration model is built and serialized these XML comments get lost. So it is better to have support for documentation comments.
So one option is to add a documentation tag and a optional attribute to the XML configuration elements to facilitate the documentations. Please add your thoughts and comments.