Escolar Documentos
Profissional Documentos
Cultura Documentos
C# VS.NET Commenting
Author: Patrick Long
Version Number, 4 October 2002
CONTENTS
1. INTRODUCTION 2
2. CONFIGURE XML COMMENTING 3
3. COMMENTING STYLES AND TAGS 4
4. MSDN STYLE DOCUMENTATION AND NDOC 5
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 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 flagged in the
VS.Net Task List. Assuming you do not have compile warnings set to errors.
/// <summary>
///
/// </summary>
/// <param name="data"></param>
public void SaveData(ref DataSet data)
{
/// <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.
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.
• 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 <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.
• 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.
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.
/// <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>
I have drawn attention to areas in the picture and their corresponding XML comment tags.