[Mono-docs-list] inconsistency in markup

[Iain McCoy]

Hey folks,

I've just started seriously poking at mono, and I figure documenting
things as I run across undocumented classes should be both useful and
easy enough (I usually run through the docs to look at the class
definitions - what methods and properties they have and so on). However,
I am bothered by inconsistency in the markup used, especially in the
"remarks" section. For the System.String class, the Insert method's
remarks look like this:
<para>In the new string returned by this method, the first
      character of <paramref name="value" /> is at <paramref
name="startIndex," /> and all characters in the
      current string from <paramref name="startIndex" /> to the end are
inserted in the new
      string after the last character of <paramref name="value"
/>.</para>

Contrast this to the class's Compare(string, string) method, which has
remarks that look like this:
<para> This method performs a case-sensitive operation.</para><block
subset="none" type="note"><para>The result of comparing any <see
cref="T:System.String" /> (including the empty string) to a null
      reference is greater than zero. The
      result of comparing two null references is zero. Upper case
letters evaluate
      greater than their lower case equivalents.</para><para>The method
uses the culture of the
      current thread to determine the ordering of individual characters.
The two strings
      are compared on a character-by-character basis.</para></block>

The latter of those has a <block subset="none" type="note"> tag, which
is not found in the first example. This tag seems redundant to me - it
seems logical that the remarks section could be considered a series of
notes (which is how it is actually used). It is conceivable that that
tag could be used to delineate separate notes in the remarks section,
but that's not happening either (see System.CharEnumerator's remarks).

My question is basically this: are there guidelines/rules to govern the
use of tags so that things happen consistently? Should there be? Should
I start seriously investigating what is actually done in the
documentation so that guidelines can be developed?
-- 
Iain McCoy <iain@mccoy.id.au>