C# and XML - XML Documentation
(Page 2 of 4 )
Documentation comments are composed of embedded XML tags. Documentation comments start with three slashes (///), and apply to a type or type-member definition.
You can also use/** /for documentation comments (notice the extra star), but this format is less supported by the IDE.
The compiler can extract the documentation comments and output an XML file. Since the compiler understands the source code, it is able to validate the comments for consistency and expands cross-references into fully qualified type IDs.
The XML documentation file can be placed in the same directory as the application or library. The Visual Studio .NET IDE will automatically load this XML file, such that the documentation is integrated with IntelliSense. If you’re producing a component library, you can use a tool such as NDoc or Sandcastle to produce HTML help files.
Here is an example of documentation comments for a type. If you’re using Visual Studio .NET, typing a///before a member automatically gets the IDE to prepopulate the summary and parameter tags. Within the documentation, starting a tag with<causes IntelliSense to give you a list of built-in XML documentation annotations.
// Filename: DocTest.cs
using System;
class Test
{
/// <summary>
/// The Foo method is called from
/// <see cref="Main">Main</see>
/// </summary>
/// <mytag>user defined tag info</mytag>
/// <param name="s">Description for s</param>
static void Foo(string s) { Console.WriteLine(s); }
static void Main() { Foo("42"); }
}
When run through the compiler using the/doc:<filename> command-line option, the following XML file is generated:
<?xml version="1.0"?>
<doc>
<assembly>
<name>DocTest</name>
</assembly>
<members>
<member name="M:Test.Foo(System.String)">
<summary>
The Foo method is called from
<see cref="M:Test.Main">Main</see>
</summary>
<mytag>user defined tag info</mytag>
<param name="s">Description for s</param>
</member>
</members>
</doc>
Every member with a documentation comment has a<member>tag with anameattribute that uniquely identifies the member. Thecref attribute in the<see>tag has been expanded to correctly refer to another code element. The custom documentation element<mytag>is just carried along with the member payload.
Next: Predefined XML Tags >>
More C# Articles
More By O'Reilly Media
|
 This article is excerpted from chapter four of C# 3.0 in a Nutshell, Third Edition, A Desktop Quick Reference, written by Joseph Albahari and Ben Albahari (O'Reilly; ISBN: 0596527578). Check it out today at your favorite bookstore. Buy this book now.
|
|
