[Mono-docs-list] Documentation Guidelines

[Brian Kerrick Nickel]

Hi,

Is there an official set of guidelines and formats for documenting .NET
libraries? One of the hardest things I've found about documenting my
stuff (and some Gtk# stuff) is that I'm not sure of the best way to
format stuff and I lack consistency.

I think it would be really helpful to have rules like:

   When describing a constructor use:
   Constructs and initializes a new instance of <see/> [...].
   
   Where [...] is "with default values"

   or a list describing parameters without using specific type names if
   possible, eg:
      "with a given message."
      "with a given IP address and port number."
      "with a given file name, seek position, and read style."
   
   OR describing the action the constructor will take with the
   parameters:
      "by reading values using the given file name, seek position, and
      read style."


I think guidelines like that would help the documentation process,
especially for new contributors.

- Brian