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?

score 41 · Accepted Answer · answered Aug 29 '08 at 16:02

41

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 '08 at 16:02

Forgotten Semicolon

13,909
2
51
61

2

See http://stackoverflow.com/questions/319632/docproject-vs-sandcastle-help-file-builder-gui for more information about Sandcastle. – Steve Mitcham Jan 12 '09 at 21:09
Where do I mention the type of arguments and return type? – Prabhat Doongarwal Jun 25 '18 at 05:43
@PrabhatDoongarwal I think it is not needed for C#. As statical typing language any IDE should tells you type on its own. – Erik Šťastný Feb 09 '22 at 18:52
Is this the best way to do it??? It seems fairly messy compared to PHPDoc style. – Angel115 Apr 08 '22 at 16:09

score 3 · Answer 2 · answered Aug 29 '08 at 16:01

3

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

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

answered Aug 29 '08 at 16:01

jason saldo

9,804
5
34
41

If i click on this link, I end up here... https://www.microsoft.com/en-us/download/details.aspx?id=55979 – Tobias Feil Jun 27 '19 at 07:30
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. – Michael Macha Feb 05 '22 at 23:31

hamishmcn · Answer 3 · 2018-02-23T18:09:42.743

2

C# has built in documentation commands Have fun!

edited Feb 23 '18 at 18:09

answered Aug 29 '08 at 16:01

hamishmcn

7,843
10
41
46

1

Unfortunately, this link is out of date – Carnix Feb 22 '18 at 15:01
1

Apparently, said link has been fixed. Ah, XML. The efficiency of prosa, combined with the readability of binary... – Markus-Hermann Jun 12 '23 at 07:06

score 1 · Answer 4 · answered Aug 29 '08 at 16:04

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.

score 1 · Answer 5 · answered Aug 29 '08 at 16:40

1

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.

answered Aug 29 '08 at 16:40

travis

35,751
21
71
94

score 0 · Answer 6 · answered Mar 31 '09 at 01:00

0

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

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

answered Mar 31 '09 at 01:00

GameFreak

2,881
7
34
38

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

6 Answers6

Linked