How to: Use the XML Documentation Features (C# Programming Guide)
XML documentation provides an effective way to document your code. The following sample presents a basic overview.
Example
// If compiling from the command line, compile with: /doc:YourFileName.xml
/// <summary>
/// Class level summary documentation goes here.</summary>
/// <remarks>
/// Longer comments can be associated with a type or member through
/// the remarks tag.</remarks>
public class TestClass : TestInterface
{
/// <summary>
/// Store for the name property.</summary>
private string _name = null;
/// <summary>
/// The class constructor. </summary>
public TestClass()
{
// TODO: Add Constructor Logic here.
}
/// <summary>
/// Name property. </summary>
/// <value>
/// A value tag is used to describe the property value.</value>
public string Name
{
get
{
if (_name == null)
{
throw new System.Exception("Name is null");
}
return _name;
}
}
/// <summary>
/// Description for SomeMethod.</summary>
/// <param name="s"> Parameter description for s goes here.</param>
/// <seealso cref="System.String">
/// You can use the cref attribute on any tag to reference a type or member
/// and the compiler will check that the reference exists. </seealso>
public void SomeMethod(string s)
{
}
/// <summary>
/// Some other method. </summary>
/// <returns>
/// Return results are described through the returns tag.</returns>
/// <seealso cref="SomeMethod(string)">
/// Notice the use of the cref attribute to reference a specific method. </seealso>
public int SomeOtherMethod()
{
return 0;
}
public int InterfaceMethod(int n)
{
return n * n;
}
/// <summary>
/// The entry point for the application.
/// </summary>
/// <param name="args"> A list of command line arguments.</param>
static int Main(System.String[] args)
{
// TODO: Add code to start application here.
return 0;
}
}
/// <summary>
/// Documentation that describes the interface goes here.
/// </summary>
/// <remarks>
/// Details about the interface go here.
/// </remarks>
interface TestInterface
{
/// <summary>
/// Documentation that describes the method goes here.
/// </summary>
/// <param name="n">
/// Parameter n requires an integer argument.
/// </param>
/// <returns>
/// The method returns an integer.
/// </returns>
int InterfaceMethod(int n);
}
The following .xml file is generated by the previous example. Notice that the comments from the interface definition are included in the class that implements the interface.
<?xml version="1.0"?>
<doc>
<assembly>
<name>XML How to</name>
</assembly>
<members>
<member name="T:TestClass">
<summary>
Class level summary documentation goes here.</summary>
<remarks>
Longer comments can be associated with a type or member
through the remarks tag.</remarks>
</member>
<member name="T:TestInterface">
<summary>
Documentation that describes the interface goes here.
</summary>
<remarks>
Details about the interface goes here.
</remarks>
</member>
<member name="M:TestInterface.InterfaceMethod(System.Int32)">
<summary>
Documentation that describes the method goes here.
</summary>
<param name="n">
Parameter n requires an integer argument.
</param>
<returns>
The method returns an integer.
</returns>
</member>
<member name="F:TestClass._name">
<summary>
Store for the name property.</summary>
</member>
<member name="M:TestClass.#ctor">
<summary>
The class constructor. </summary>
</member>
<member name="M:TestClass.SomeMethod(System.String)">
<summary>
Description for SomeMethod.</summary>
<param name="s"> Parameter description for s goes here.</param>
<seealso cref="T:System.String">
You can use the cref attribute on any tag to reference a type or member
and the compiler will check that the reference exists. </seealso>
</member>
<member name="M:TestClass.SomeOtherMethod">
<summary>
Some other method. </summary>
<returns>
Return results are described through the returns tag.</returns>
<seealso cref="M:TestClass.SomeMethod(System.String)">
Notice the use of the cref attribute to reference a specific method. </seealso>
</member>
<member name="M:TestClass.Main(System.String[])">
<summary>
The entry point for the application.
</summary>
<param name="args"> A list of command line arguments.</param>
</member>
<member name="P:TestClass.Name">
<summary>
Name property. </summary>
<value>
A value tag is used to describe the property value.</value>
</member>
</members>
</doc>
Compiling the Code
To compile the example, you can type the following command line: csc XMLsample.cs /doc:XMLsample.xml.
This command creates the XML file XMLsample.xml, which you can view in a browser or in a word processor.
Alternatively, in Solution Explorer, right-click the project's name and then click Properties. On the Build tab, select XML documentation file in the Output section, and then enter a name for the .xml file.
Robust Programming
XML documentation starts with ///. When you create a new project, the IDE adds some /// lines for you. The processing of these comments has the following restrictions:
The documentation must be well-formed XML. If the XML is not well-formed, a warning is generated and the documentation file contains a comment that says that an error has been encountered.
Developers can create their own sets of tags. However, there is a recommended set of tags (see the See Also section of this topic) that have special meanings, as described in the following examples:
The <param> tag is used to describe parameters. If this tag is used, the compiler verifies that the parameters exist and that all parameters are described in the documentation. If the verification fails, the compiler issues a warning.
The cref attribute can be attached to any tag to provide a reference to a code element. The compiler verifies that the code element exists. If the verification fails, the compiler issues a warning. The compiler respects any using statements when it looks for a type described in the cref attribute.
The <summary> tag is used by IntelliSense inside Visual Studio to display additional information about a type or member.
Note
The XML file does not provide full information about the type and members. For example, it does not contain any type information. To get full information about a type or member, the documentation file must be used together with reflection on the actual type or member.
See Also
Reference
XML Documentation Comments (C# Programming Guide)
Concepts
Change History
Date |
History |
Reason |
|---|---|---|
|
April 2011 |
Added an interface to the example. |
Customer feedback. |