.Net XML Documentation Standard

Question

I have looked at the Suggested related questions but none of them are what I am looking for. As a new developer I am trying hard to follow best practices and documentation is a big one. As I go I am trying to create XML docs in my code. I discovered the GhostDoc plug in which helps speed this up.

My question though is; Is there a commonly excepted standard as to what should be included in the XML. By default I am using <Summary><Param><Returns> when applicable. Are there others? Should I include author? How? <Patrick></Patrick>? Is <Remarks> worth the time?

I would be grateful for any guidance on this. Thank You!

Answer 1

I definitely think the <remarks> tag is worth the time, as it allows you to elaborate on the summary, and more knowledge is always a good thing.

I also think that the <typeparamref> is important for generic classes.

Inside each of your elements, you should also make use of the <see> tag as well, so that you can link documentation together.

Outside of the standard tags, I add <author> to show the original author of the class/method/property/etc, etc as well as a <created> tag to indicate when the member was created. In a team environment, you will probably want something more robust, like so:

<revisions>
  <revision>
    <author>Nicholas Paldino</author>
    <revised>2009-02-01</revised>
  </revision>
  <revision>
    <author>Mr_Mom</author>
    <revised>2009-02-11</revised>
  </revision>
</revisions>

Answer 2

I only recently found this guide to XML documentation. It's really handy. It's not a best practice guide as such, but it's good at covering the tags which aren't used very often and thus get forgotten.