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?
Add a comment
|
6 Answers
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.
answered Aug 29, 2008 at 16:02
Forgotten Semicolon
14.2k2 gold badges53 silver badges61 bronze badges
4 Comments
Steve Mitcham
See stackoverflow.com/questions/319632/… for more information about Sandcastle.
Prabhat Doongarwal
Where do I mention the type of arguments and return type?
Erik Šťastný
@PrabhatDoongarwal I think it is not needed for C#. As statical typing language any IDE should tells you type on its own.
Angel115
Is this the best way to do it??? It seems fairly messy compared to PHPDoc style.
/// <summary>
///
/// </summary>
/// <param name="strFilePath"></param>
2 Comments
Tobias Feil
If i click on this link, I end up here... microsoft.com/en-us/download/details.aspx?id=55979
Michael Macha
While links are helpful, you could improve this answer by discussing the precise portion of the document that relates to answering the question, or explaining why it's beneficial. You could, as an example, state that it's the Microsoft-directed standard for inline documentation since 2002.
C# has built in documentation commands Have fun!
2 Comments
Carnix
Unfortunately, this link is out of date
Markus-Hermann
Apparently, said link has been fixed. Ah, XML. The efficiency of prosa, combined with the readability of binary...
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.
Comments
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.
Comments
I was always told to use block comments opened with 2 or more asterisks do delimit documentation comments.
/**
Documentation goes here.
(flowerboxes optional)
*/
