The following XML comment tags are officially supported in
the .NET Framework: c,code, example, exception, include, list, para, param,
paramref, permission, remarks, returns, see, seealso, summary and typeparam.
Note that typeparam is supported from version 2.0 of the .NET Framework; all of
the other tags are supported from .NET 1.0. In version 2.0 of the .NET
Framework, both C# and VB.NET support the same XML comment tags.
c: This tag is used to denote code,
so it can be used to identify sample code associated with a particular entity
within the source code. Note that the tag can only be used to represent a
single line of code or to denote that some of the text on a line should be
marked up as code. Example: <c>Dim MyObject As MyType</c>
code: This tag is used to denote
more than one line of code, so it can be used to identify longer areas of sample
code.
example: This tag may be used to
describe an example of using a particular method or class. It is possible to
include code samples within the example tag by making use of either the c or
code tags.
exception: The exception tag allows
a method's exception handling to be documented. The cref attribute allows the
namespace of the exception handler to be included. Example: <exception
cref="System.Exception" >Throws an exception if the customer is
not found.</exception>.
include: This tag allows documentation
to be imported from an external XML file rather than being stored within the
source code itself. As such, it may be useful if the documentation is written
by people other than the software developers (e.g. technical writers).
list: This tag allows bulleted or
numbered lists or tables to be added to XML comments.
para: This tag indicates that the
text within the tags should be formatted within a paragraph. As such, it can be
used to format text within other tags such as summary or returns. Example:
<para>This is a paragraph</para>
param: The param tag is used to
document a method's arguments. The tag's name attribute specifies the name of
the argument to which the tag refers. The tag is also used by Visual Studio's
Intellisense system to show a description of a method's arguments. It is also
used by the Visual Studio Object Browser. Example: <param
name="FileName" >The filename of the file to be
loaded.</param>.
paramref: This tag can be used to
refer to a method's argument elsewhere within the method's XML comments. The
tag's name attribute specifies the name of the argument to which the tag
refers. Note that the param tag is actually used to describe the parameter.
Example: Use the <paramref name="FileName"/> argument to
specify which filename is loaded.
permission: The permission tag can
be used to describe any special permissions a specific object needs. The object
to which the permission refers is included as the cref attribute. Example:
Class needs to write to the file system and ensure the user has appropriate
access.
summary: The summary tag describes a
method or class, so it is the most important tag. As well as being used in a
project's documentation, the tag is also used by Visual Studio's Intellisense
system to show a description of the method or class being referenced. It is
also used by the Visual Studio Object Browser.
remarks: The remarks tag can be used
to supply additional information about a method or class, supplementing the
details given in the summary tag. As with the summary tag, this tag is also
used by Visual Studio's Intellisense system and the Visual Studio Object
Browser.
returns: Describes the return value
of a method. Example: <returns>True if user has permission to access the
resource, otherwise False.</returns>.
see: The see tag is used to
reference other entities (such as classes) in the project. The see tag is
intended for use within other tags such as the summary tag. Example:
<seealso cref="System.Configuration"/>
seealso: The seealso tag resembles
the see tag and has identical syntax, except that the text is intended to be
used to create a separate seealso section for the entity's documentation.
typeparam: Typeparam is used in an
identical way to param, except that it is used to document a type associated
with a generic class or function.
value: Value is only used when
documenting a property and is used to describe the value assigned to that. The
comment is not required for properties that are marked as read only. Example:
<value>Sets the employee's salary</value>
