MSDN like documentation for Xml-files?

[Ole Hanson]

I would like to be able to generate documentation for a custom configuration
file (xml) to enable future support engineers to understand applicable
values to the various elements inside the configuration file. (see below for
sample).

Does any program exist (like NDoc) that is able to generate MSDN like
documentation?

<!-- CONFIGURATION SECTION -->
<configurationSection>
<caching>
<!--
Should caching be used by the Configuration system ?
Using caching greatly improves performance
Values:
"false" : Do not use
"true" : Do use
-->
<add key="useCaching" value="true"/>
<!-- Time To Live [Sec.] (when using SQL Storage) -->
<add key="TTL" value="234"/>
</caching>

Thanks!

/Ole

[Derek Harmon]

"Ole Hanson" <[e-mail]> wrote in message news:eJ**************@TK2MSFTNGP14.phx.gbl...

I would like to be able to generate documentation for a custom configuration
file (xml)
The free-form nature of markup is challenging for a piece of
documentation software to scan it for free-form comments and
associate them with elements and attributes.

: : <caching>
<!--
Should caching be used by the Configuration system ?
Using caching greatly improves performance
Values:
"false" : Do not use
"true" : Do use
-->
<add key="useCaching" value="true"/>

That may appear to be a logical comment to create documentation
from to you, but to documentation software there's no way to make
the association between the boolean values in the comment and that
they belong in the value attribute of the add element (and not in the
key attribute, or as a child text node). Further, since the comment
has arbitrary formatting, it's a feat of natural language processing
just to extract relevant pieces of information to tie to particular
items in the XML Infoset of your document.

Instead of interpreting free-form comments in instance documents,
a better way presented itself to the XML Schema WG and that's
why XML schema support <xs:documentation> tags. These are
nested within the definitions for XML element and attributes so
they directly correlate to these items in the XML Infoset for your
document.

Documenting XML files in a general-purpose manner amenable
to tools support for creating MSDN-style 'man' page requires
this sort of XML schema documentation. A general-purpose
documentation tool can then operate on this input to produce
the help documentation.

XML Spy has documentation-generation support (although not
specifically to the MSDN look-and-feel) that works this way.
If there is an NDoc documenter for XML documentation, it'll
probably also operate on <xs:documentation> tags.
Derek Harmon