Click here to Skip to main content
15,861,168 members
Articles / Programming Languages / C#
Article

C# Documenting and Commenting

Rate me:
Please Sign up or sign in to vote.
4.74/5 (89 votes)
20 Jan 20036 min read 723K   240   87
Use C# Comment tags to produce great documentation and code

Introduction

Most of us will have experienced the dread of updating documentation at some point or other. C# and Visual Studio .NET (VS.NET) give us the ability to maintain code and documentation in the same file, which makes the whole process a lot easier. VS.NET does this by taking specially marked and structured comments from within the code and building them into an XML file. This XML file can then be used to generate human-readable documentation in a variety of forms including web pages, MSDN style documentation and Intellisense within the code window.

Configure XML Commenting

VS.NET produces XML comments by taking specially marked and structured comments from within the code and building them into an XML file. This XML file can then be used to generate human-readable documentation in a variety of forms including web pages, MSDN style documentation and Intellisense within the code window. The first thing you need to do is enable the XML commenting feature for your VS.NET project.

  1. Right Click on the project in the solution explorer and select "Properties".
  2. Within the properties dialog double click on the “Configuration Properties” node.
  3. The Build node should be already selected and you should be able to see the “XML Documentation File” entry under “Outputs”. Here is where you must enter the name of the XML file that will contain the comment data. You can call the file what you like, but for compatibility with all the features of XML commenting, it should take the form of MyAssemblyName.Xml e.g. Adjuster.BusinessServices.dll has a related XML file called Adjuster.BusinessServices.Xml

With this enabled, your XML comment data file will be rebuilt each time you build your project. Any problems that occur when trying to generate the file will not prevent a build but will be flagged in the VS.NET Task List. Assuming you do not have compile warnings set to errors.

Image 1

VS.NET Task List flagging XML commenting error.

With that enabled you can start to use the special XML tags in your procedure “headers”. To get you started, place the cursor on the line directly above a procedure’s definition. Once there, press the “/” key three times, this will automatically insert a summary tag into your code. If the procedure had any arguments there should now be a param tag for each one.

C#
/// <summary>
/// 
/// </summary>
/// <param name="data"></param>
public void SaveData(ref DataSet data)
{

}

The SaveData code above is what is inserted as default

C#
/// <summary>
/// Connects to the database and attempts to apply 
/// all adds, updates and deletes
/// </summary>
/// <param name="data">a dataset, passed by reference, 
/// that contains all the 
/// data for updating>/param>
public void SaveData(ref DataSet data)
{

}

This SaveData code is after I have added my comments describing what the routine does in the summary tag and what the data parameter is. This very simple action has given us enough to provide basic documentation including intellisense just like that provided by the .NET Framework assemblies.

Image 2

It is clear from just this feature, how useful XML commenting is. When you include a reference to a .NET project that has XML commenting enabled, the XML documentation file we named earlier is copied over along with the binary to the current project’s \bin directory. This gives you the intellisense across assemblies.

The summary tag is the most basic of tags. The list below is the complete set currently supported by VS.NET. The ones marked with a * are the ones I feel are the most useful and the ones we will be dealing in the following examples.

  • c
    The c tag gives you a way to indicate that text within a description should be marked as code. Use code to indicate multiple lines as code.

  • code*
    The code tag gives you a way to indicate multiple lines as code. Use <c> to indicate that text within a description should be marked as code.

  • example*
    The example tag lets you specify an example of how to use a method or other library member. Commonly, this would involve use of the code tag.

  • exception*
    The exception tag lets you specify which exceptions a class can throw.

  • include
    The include tag lets you refer to comments in another file that describe the types and members in your source code. This is an alternative to placing documentation comments directly in your source code file.

  • para
    The para tag is for use inside a tag, such as <remarks> or

    XML
    <returns>
    , and lets you add structure to the text.

  • param*
    The param tag should be used in the comment for a method declaration to describe one of the parameters for the method.

  • paramref
    The paramref tag gives you a way to indicate that a word is a parameter. The XML file can be processed to format this parameter in some distinct way.

  • permission*
    The permission tag lets you document the access of a member. The System.Security.PermissionSet lets you specify access to a member.

  • remarks*
    The remarks tag is where you can specify overview information about a class or other type. <summary> is where you can describe the members of the type.

  • returns
    The returns tag should be used in the comment for a method declaration to describe the return value.

  • see
    The see tag lets you specify a link from within text. Use <seealso> to indicate text that you might want to appear in a See Also section.

  • seealso*
    The seealso tag lets you specify the text that you might want to appear in a See Also section. Use <see> to specify a link from within text.

  • summary*
    The summary tag should be used to describe a member for a type. Use <remarks> to supply information about the type itself.

  • value*
    The value tag lets you describe a property. Note that when you add a property via code wizard in the Visual Studio .NET development environment, it will add a <summary> tag for the new property. You should then manually add a <value> tag to describe the value that the property represents.

MSDN Style Documentation and NDOC

We have taken the intellisense format as far as it will go, but there is much more we can do with MSDN style documentation. There is a tool that comes with VS.NET that you will find at “Tools|Build Comment Web Pages…” which will take your C# XML comments from source files and generate linked HTML files. This comes straight out of the box so should not be totally disregarded. But if you want to create easy-to-use, helpful, cross-referenced and attractive documentation, then I can strongly recommend the free, open source tool NDoc. The screenshot below is taken from a compiled help file produced from NDoc and is an example of the quality it can produce.

Image 3

The two routines below will show the correct usage for most of the XML comment tags we saw earlier. The cref attribute of the exception tag is used for cross-referencing to an Exception type. This attribute is also used in the seealso, permission and see tags to reference a type. The type must be available from the current compilation environment. The compiler checks that the referenced type exists and passes relevant data to the output XML.

C#
/// <summary>
/// Gets or sets the age of the person involved in the accident
/// </summary>
/// <value>Age of the claimant.</value>
/// <remarks> The value must be numeric.
/// </remarks>
/// <exception cref="System.ApplicationException">Thrown when a non-
/// numeric value is assigned.</exception>
public string Age
{
}

This Age property once processed by NDoc will produce this.

Image 4

I have drawn attention to areas in the picture and their corresponding XML comment tags.

C#
/// <summary>
/// Connects to the database and attempts to apply all adds, 
/// updates and deletes
/// </summary>
/// <seealso cref="Adjuster.BusinessServices.Accident"/> 
/// <param name="data">a dataset, passed by reference, 
/// that contains all the 
/// data for updating</param>
/// <example> This sample shows how to call the SaveData 
/// method from a wireless device.
/// <code>
/// 
///AccidentCRUD accCRUD = new Adjuster.BusinessServices.AccidentCRUD();
///accCRUD.SaveData(ref ds);
///
///</code>
///</example>
///<permission cref="System.Security.PermissionSet">Everyone 
///can access this method.</Permission>
public void SaveData(ref DataSet data)
{
}

This SaveData method once processed by NDoc will produce this

Image 5

Again I have drawn attention to areas in the picture and their corresponding XML comment tags. The Accident cross-reference in the “See Also” section is the only one that I added. By default NDoc adds cross-referencing for the parent class, the parent class’ members and the parent class’ namespace.

With the combination of NDoc and VS.Net & C#’s ability to produce these comments you can get great technical documentation at a level so close to the code, that there is absolutely no excuse for it not telling it as it is.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


Written By
Web Developer
Europe Europe
I have been programming now for 10 years starting with COBOL, CICS and DB2 and ending up with ASP.NET, WPF, and various web technologies.

I work for Munkiisoft in the UK.

Check out my blog here

Comments and Discussions

 
QuestionHow document an Item in enum object? Pin
ReneTrevi11-Mar-15 9:20
ReneTrevi11-Mar-15 9:20 
AnswerRe: How document an Item in enum object? Pin
phil.o11-Mar-15 9:51
professionalphil.o11-Mar-15 9:51 
GeneralRe: How document an Item in enum object? Pin
ReneTrevi11-Mar-15 12:31
ReneTrevi11-Mar-15 12:31 
GeneralRe: How document an Item in enum object? Pin
phil.o11-Mar-15 16:37
professionalphil.o11-Mar-15 16:37 
QuestionWhat is the value of the value tag? Pin
George Henry 195430-Aug-13 6:27
George Henry 195430-Aug-13 6:27 
I mean, of what use or benefit is it other than encouraging redundancy and pointless typing? I imagine you can discern my bias - which I retain after consulting [<a href="http://msdn.microsoft.com/en-us/library/azda5z79.aspx" target="_blank" title="New Window">MSDN</a>]. While looking at the code, I can plainly see the relationship of the property to its backing variable; documentation thereof is not needed. From a higher level, I do not need to know about that relationship; in general, a user of the property should not know or care how it is implemented.

George Henry
QuestionNice article Pin
Pavel Vladov14-Nov-12 3:53
Pavel Vladov14-Nov-12 3:53 
GeneralCommercial option for .NET documentation Pin
Richard Slogget5-Oct-12 12:31
Richard Slogget5-Oct-12 12:31 
Questionhow can i use this dll in my code Pin
sushilabhanvar23-Jun-09 4:40
sushilabhanvar23-Jun-09 4:40 
GeneralIs there a way to document overloaded methods Pin
Clive D. Pottinger30-May-08 12:16
Clive D. Pottinger30-May-08 12:16 
GeneralMessage Closed Pin
1-Oct-08 7:50
stonber1-Oct-08 7:50 
GeneralRe: Is there a way to document overloaded methods Pin
Clive D. Pottinger2-Oct-08 3:16
Clive D. Pottinger2-Oct-08 3:16 
GeneralRe: Is there a way to document overloaded methods Pin
deepakpaggi24-Sep-09 23:13
deepakpaggi24-Sep-09 23:13 
GeneralRe: Is there a way to document overloaded methods Pin
vamyip13-Aug-10 0:26
vamyip13-Aug-10 0:26 
GeneralGreat job. Also SandCastle instead of NDoc Pin
Reve10115-Nov-07 10:55
Reve10115-Nov-07 10:55 
QuestionC# properties view Pin
hanseh16-Oct-07 20:05
hanseh16-Oct-07 20:05 
AnswerRe: C# properties view Pin
Patrick Long16-Oct-07 21:07
Patrick Long16-Oct-07 21:07 
QuestionRe: C# properties view Pin
hanseh16-Oct-07 22:48
hanseh16-Oct-07 22:48 
GeneralThanks a million Pin
bigblockfw14-Apr-07 14:32
bigblockfw14-Apr-07 14:32 
GeneralXML File Copying Problem Pin
N a v a n e e t h18-Jan-07 23:21
N a v a n e e t h18-Jan-07 23:21 
GeneralRe: XML File Copying Problem Pin
Patrick Long19-Jan-07 11:09
Patrick Long19-Jan-07 11:09 
GeneralRe: XML File Copying Problem Pin
N a v a n e e t h5-Feb-07 22:32
N a v a n e e t h5-Feb-07 22:32 
QuestionNice article, Pin
abdulmalikm5-Dec-06 3:23
abdulmalikm5-Dec-06 3:23 
GeneralProblem documenting reference parameter Pin
Ariston Darmayuda14-May-06 21:11
Ariston Darmayuda14-May-06 21:11 
QuestionEnum member descriptions? Pin
Anonymous13-Sep-05 9:41
Anonymous13-Sep-05 9:41 
AnswerRe: Enum member descriptions? Pin
Alexander Lowe16-Sep-05 8:10
sussAlexander Lowe16-Sep-05 8:10 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.