Is there a standard (like phpdoc or python's docstring) for commenting C# code?

Question

Is there a standard convention (like phpdoc or python's docstring) for commenting C# code so that class documentation can be automatically generated from the source code?

Answer 1

/// <summary>
///
/// </summary>
/// <param name="strFilePath"></param>

http://msdn.microsoft.com/en-us/magazine/cc302121.aspx

Answer 2

C# has build in documentation commands: msdn link Have fun!

Answer 3

You can use XML style comments, and use tools to pull those comments out into API documentation.

Here is an example of the comment style:

/// <summary>
/// Authenticates a user based on a username and password.
/// </summary>
/// <param name="username">The username.</param>
/// <param name="password">The password.</param>
/// <returns>
/// True, if authentication is successful, otherwise False.
/// </returns>
/// <remarks>
/// For use with local systems
/// </remarks>
public override bool Authenticate(string username, string password)

Some items to facilitate this are:

GhostDoc, which give a single shortcut key to automatically generate comments for a class or method. Sandcastle, which generates MSDN style documentation from XML comments.

Answer 4

Microsoft uses "XML Documentation Comments" which will give IDE intellisense descriptions and also allow you to auto-generate MSDN-style documentation using a tool such as Sandcastle if you turn on the generation of the XML file output.

To turn on the generation of the XML file for documentation, right click on a project in visual studio, click "Properties" and go to the "Build" tab. Towards the bottom you can specify a location for your XML comments output file.

Answer 5

The previous answers point out the XML syntax perfectly. I just wanted to throw in my recommendation for the free (and open-source) nDoc help library generator that parses all comments in a project.

Answer 6

Great answers! Thanks everyone.

Answer 7

I was always told to use block comments opened with 2 or more asterisks do delimit documentation comments.

/**
Documentation goes here.
(flowerboxes optional) 
*/