It is important to provide adequate documentation for all of your applications. Provide enough comments to enable a developer who was not involved in creating the original application to follow and understand how the application works. Visual Studio allows you to write documentation and easily integrate it to IDE.
C# provides several mechanisms for adding comments to application code: single-line comments, multiple-line comments, and XML-generated documentation.
Generating XML Documentation
You can use C# comments to generate XML documentation for your applications.
Documentation comments begin with three forward slashes (///) followed by an XML documentation tag. For examples, below:
There are a number of suggested XML tags that you can use. (You can also create your own.) The following table shows some XML tags and their uses.
| Tag | Purpose |
| <summary> … </summary> | To provide a brief description. Use the <remarks> tag for a longer description. |
| <remarks> … </remarks> | To provide a detailed description. This tag can contain nested paragraphs, lists, and other types of tags. |
| <para> … </para> | To add structure to the description in a <remarks> tag. This tag allows paragraphs to be delineated. |
| <list type=”…”> … </list> | To add a structured list to a detailed description. The types of lists supported are “bullet,” “number,” and “table.” Additional tags (<term> … </term> and <description> … </description>) are used inside the list to further define the structure. |
| <example> … </example> | To provide an example of how a method, property, or other library member should be used. It often involves the use of a nested <code> tag. |
| <code> … </code> | To indicate that the enclosed text is application code. |
| <c> … </c> | To indicate that the enclosed text is application code. The <code> tag is used for lines of code that must be separated from any enclosing description; the <c> tag is used for code that is embedded within an enclosing description. |
| <see cref=”member“/> | To indicate a reference to another member or field. The compiler checks that “member” actually exists. |
| <seealso cref=”member“/> | To indicate a reference to another member or field. The compiler checks that “member” actually exists. The difference between <see> and <seealso> depends upon the processor that manipulates the XML once it has been generated. The processor must be able to generate See and See Also sections for these two tags to be distinguished in a meaningful way.
<exception> … </exception> To provide a description for an exception class. |
| <permission> … </permission> | To document the accessibility of a member. |
| <param name=”name“> … </param> | To provide a description for a method parameter. |
| <returns> … </returns> | To document the return value and type of a method. |
| <value> … </value> | To describe a property. |
You can compile the XML tags and documentation into an XML file by using the C# compiler with the /doc option:
csc myprogram.cs /doc:mycomments.xml
If there are no errors, you can view the XML file that is generated by using a tool such as Internet Explorer.
The purpose of tuhe /doc option is only to generate an XML file. To render the file, you will need another processor. Internet Explorer displays a simple rendition that shows the structre of the file and allows tags to be expanded or collapsed, but it will not, for example, display the <list type=”bullet”> tag as a bullet.
Using the documentation integrated with the Visual Studio IDE
Upon you have written the XML documentation .NET automatically will become it available in developing time, exactly who happens with the internal class and methods.
