CODEWITHSUNDEEP
c#comments
Mark Biek
Mark Biek

Reputation: 150739

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

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?

Upvotes: 41

Views: 27014

Answers (6)

hamishmcn
hamishmcn

Reputation: 7981

C# has built in documentation commands Have fun!

Upvotes: 3

GameFreak
GameFreak

Reputation: 2931

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

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

Upvotes: 0

travis
travis

Reputation: 36463

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.

Upvotes: 1

Dan Herbert
Dan Herbert

Reputation: 103387

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.

Upvotes: 1

Forgotten Semicolon
Forgotten Semicolon

Reputation: 14100

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.

Upvotes: 43

jason saldo
jason saldo

Reputation: 9950

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

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

Upvotes: 3

Related Questions