[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.