tags:

views:

779

answers:

7

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?

+3  A: 
/// <summary>
///
/// </summary>
/// <param name="strFilePath"></param>

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

jms
A: 

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

hamishmcn
+12  A: 

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.

Forgotten Semicolon
See http://stackoverflow.com/questions/319632/docproject-vs-sandcastle-help-file-builder-gui for more information about Sandcastle.
Steve Mitcham
A: 

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.

Dan Herbert
+1  A: 

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.

travis
A: 

Great answers! Thanks everyone.

Mark Biek
A: 

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

/**
Documentation goes here.
(flowerboxes optional) 
*/
GameFreak
That is in java, i think so
Jhonny D. Cano -Leftware-