Commenting and Documenting C# Code
In C#, generally we write the comments for code by using double slash (//). But C# provides the better way to comment our C# code by using XML format. Even we can copy all comments from C# project to make documentation for our project. In this article we learn how to comment our C# code in XML format and document these comments to XML file.
C# Compiler takes the responsibility to convert comments into XML documentation. To document your C# types in XML format, first step is to make use of the new triple slash (///) code comment notations as shown below. To comment C# code in XML format Visual Studio 2008 IDE will generate documentation skeletons by entering triple slash(///) as shown below.
///<summary>
/// This Class Provides methods to access Employee Information
///</summary>
classEmployee
{
///<summary>
/// This method returns Employee Info
///</summary>
///<param name="Id"></param>
///<param name="Name"></param>
///<param name="Sal"></param>
privatevoid EmpInfo(int Id, string Name, decimal Sal)
{
}
}
As shown above, there are different XML elements like <summary>,<param> available to comment the C# Code. Below we can find some of the elements to comment the code.
- <c>: Indicates that the following text should be displayed in a specific“code font”
- <code>: Indicates multiple lines should be marked as code
- <example>: Mocks up a code example for the item you are describing
- <exception>: Documents which exceptions a given class may throw
- <list>:Inserts a list or table into the documentation file
- <param>:Describes a given parameter
- <paramref>:Associates a given XML tag with a specific parameter
- <permission>:Documents the security constraints for a given member
- <remarks>:Builds a description for a given member
- <returns>: Documents the return value of the member
- <see>:Cross-references related items in the document
- <seealso>:Builds an “also see” section within a description
- <summary>:Documents the “executive summary” for a given member
- <value>:Documents a given property
We can generate XML documentation from these XML elements by using Visual Studio 2008. Right Click on Solution Explorer, select Properties and click on Build tab. In Build tab, under Output section select XML documentation file check box and provide the path for the XML documentation file as shown below.
Build your project and you can find XML documentation file CSharpDocmentationExp.XML in bin\Debug\CSharpDocmentationExp.XML folder and the content of XML file is as shown below.
You can convert this XML file into HTML format manually or by using any third party tool.
