[Mono-docs-list] MonoDoc XML and Overloads

[Jason Diamond]

Hi.

I was just looking at the MonoDoc document and noticed that it doesn't have
any sort of construct to document overloaded members. Take a look at the
System.Xml.XmlNode.Item overloads, for example. If you look at the page that
summarizes all the overloads of that property [1], you'll see that the
summary at the top of that page doesn't match the summary at the top of each
of the individual overload pages [2][3].

In NDoc, we added support for an <overloads> element. This isn't supported
or documented anywhere by Microsoft but we wanted to have the same control
that they obviously have. We currently check the <overloads> element for
<summary>, <example>, and <note> elements (see the
System.Xml.XmlDocument.Load overloads [4] for an example of a note in the
overloads page). The <overloads> element can be "attached" to any overload
in the source file. If there is no member with an <overloads> element, then
we just grab the first <summary> from the first overloaded memeber. MonoDoc
can obviously do something different here since you're not extracting your
documentation from the source. It should still be possible to convert
MonoDoc to something that looks like the CSC-generated XML documentation
file so that we can feed it to NDoc.

Hope this helps,
Jason

[1]
ms-help://MS.NETFrameworkSDK/cpref/html/frlrfSystemXmlXmlNodeClassItemTopic.
htm
[2]
ms-help://MS.NETFrameworkSDK/cpref/html/frlrfSystemXmlXmlNodeClassItemTopic1
.htm
[3]
ms-help://MS.NETFrameworkSDK/cpref/html/frlrfSystemXmlXmlNodeClassItemTopic2
.htm
[4]
ms-help://MS.NETFrameworkSDK/cpref/html/frlrfSystemXmlXmlDocumentClassLoadTo
pic.htm