There are nine primary tags:
, , , , , , , , and .
In this context, the
tag is used to describe a type such as a class:
///The C# documentation recommends using
/// Class that contains functions to do
/// transformations to help files.
to describe a type and a tag to describe a type member. Oddly, if you start a comment before a type using the /// combination, the Visual Studio .NET IDE will still insert a tag. Therefore, tags need to be inserted manually.
tag is the tag found most often in a C# source file. This tag is used to describe type members, including methods, properties, and fields:
/// This XmlDocument based attribute contains the
/// XML documentation for the project.
tag can describe types as well, but it is not recommended. The XML comment documentation recommends that the tag be used for describing types.
tag is used to mark the beginning of an example showing how to use the item. The example can be any valid text, but most often it is a snippet of code:
///If code is used, it is usually marked with a
/// // create the class that does translations
/// GiveHelpTransforms ght = new GiveHelpTransforms();
/// // have it load our XML into the SourceXML property
tag will be discussed in the section on support tags.
tag documents the exceptions, if any, that the item may throw. If more than one exception may be thrown, then more than one of these tags may be used. Unlike most of the tags, the tag has one attribute, cref. The value of this attribute is the name of the exception that could be thrown. This must be a valid class because the C# parser will verify it and extract the context information to put into the XML documentation. I will explain this later.
I did not throw any exceptions in the code for this article, but here is an example of how the cref attribute can be used with the
///The tag describes the parameters of a method or property. It is automatically inserted by the IDE when using the three forward slashes before a method. The tag has one attribute, name, which is simply the same name that the parameter has in the source:
/// Normally, a discussion on any exceptions thrown would go here.
/// The path to the file containing theMember access is identified with the
/// source XML.
tag. The text that is assigned to it sets permission-related descriptions. There is no requirement for the value for this tag. Permission is one possibility, with values such as public, private, protected, and so on. Scope is another possible value, with information about whether the method is static. However, you are free to put whatever value you must have here.
tag has one attribute—cref. The documentation describes the use of cref in this context as "a reference to a member or field that is available to be called from the current compilation environment." It is usually set to System.Security.PermissionSet:
tag is similar to the tag, but it's used to describe what the method or property returns:
The HTML for a list of types based on the XML
///The XML compiler will identify the content of the symbol and use it accordingly in the compiled XML documentation. I'll discuss this again in the section on the XML documentation file.