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

John Barnette jbarn@httcb.net
Wed, 13 Mar 2002 17:22:56 -0700


At 05:05 PM 3/13/2002, Jason Diamond wrote:
> > --- 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).

Jason, thanks for this.  I'd have to agree that your method for dealing 
with the tags is nicely consistent.


~ j.