[Mono-docs-list] Re: [Mono-list] XML documentation question for all.

[Jason Diamond]

> --- FROM IRC ---
> <jbarn> Afternoon kids.
> <jbarn> XML doc question for anyone interested: How would you define the
> purpose of the <remarks> and <summary> tags?  Standards, MS documentation,
> and books seem to conflict.  MS documentation conflicts internally, even.
:-(
> --- END  IRC ---

Yes, the Microsoft documentation is unfortunately confusing (and, in my
opinion, buggy). NDoc takes the position that both types and members can
have both a <summary> and <remarks>. The <summary> is what appears at the
top of a type or member page in MSDN and the <remarks> are what appears in
the "Remarks" section below the syntax block and above the examples. The
<summary> usually contains a single sentence and the <remarks> can contain
many paragraphs. I like to think of the <summary> as being the first
sentence in a JavaDoc comment (JavaDoc takes the first sentence in the first
paragraph and uses that as a short description for the type or member which
is really lame way to do it).

We've gotten some questions about why we're not consistent with what MSDN
says in certain places but most people seem to think that our implementation
makes the most sense. I try to back up my opinion with the fact that typing
three slashes in a row above a type or member in VS.NET makes the editor
insert an empty <summary> element for you to fill in. It does NOT insert a
<summary> only for members and <remarks> only for types like MSDN seems to
imply it should.

There's a new whitepaper on XML documentation comments by a program manager
on the C# compiler team at [1]. It says the same thing regarding the
"difference" between <summary> and <remarks> but all of the examples use
<summary> for both types and members. Everybody at Microsoft must be cutting
and pasting from the same source.

Hope this helps,
Jason

[1]
http://www.gotdotnet.com/team/csharp/Information/Whitepapers/XMLDocs.doc