The XML tutorial for adding XML comments in the XML Documents, are added immediately before the property, method, or class definition they are associated with. Visual Studio automatically adds an XML comment block when you type the shortcut code /// in C# before a member or class declaration. In some cases the XML comments will already be present in code generated by the supplied project templates.
The < c > Tag
The < c > tag indicates that the enclosed text should be formatted as code, rather than normal text. It is used for code that is included in a normal text block. The structure of < c > is simple, with any text appearing between the opening and closing tags being marked for formatting in the code style.
< c > code-formatted text < /c >1: /// <summary>
2: /// The <c>UserId</c> property is used in conjunction with other properties
3: /// to setup a user properly. Remember to set the <c>Password</c> field too.
4: /// </summary>
5: public string UserId { get; set; }
The < code > Tag
If the amount of text in the documentation you need to format as code is more than just a phrase within a normal text block, you can use the
< code > tag instead of < c > .
This tag marks everything within it as code, but it is a block - level tag, rather than a character - level tag. The syntax of this tag is a simple opening and closing tag with the text to be formatted inside, as shown here in the XML tutorial for XML Documents:
<code>The <code> tag can be embedded inside any other XML comment tag. The following code shows an example of how it could be used in the summary section of a property definition:
Code-formatted text
Code-formatted text
</code>
1: /// <summary>
2: /// The <c>UserId</c> property is used in conjunction with other properties
3: /// to setup a user properly. Remember to set the <c>Password</c> field too.
4: /// For example:
5: /// <code>
6: /// myUser.UserId = "daveg"
7: /// myUser.Password = "xg4*Wv"
8: /// </code>
9: /// </summary>
10: public string UserId { get; set; }
The <example> Tag
A common requirement for internal documentation is to provide an example of how a particular procedure or member can be used. The <example> tags indicate that the enclosed block should be treated as a discrete section of the documentation, dealing with a sample for the associated member. Effectively, this doesn’t do anything more than help organize the documentation, but used in conjunction with an appropriately designed XML style sheet or processing instructions, the example can be formatted properly. The other XML comment tags, such as <c> and <code>, can be included in the text inside the <example> tags to give you a comprehensively documented sample. The syntax of this block-level tag is simple:
<example>
Any sample text goes here.
</example>
1: /// <summary>
2: /// The <c>UserId</c> property is used in conjunction with other properties
3: /// to setup a user properly. Remember to set the <c>Password</c> field too.
4: /// </summary>
5: /// <example>
6: /// <code>
7: /// myUser.UserId = "daveg"
8: /// myUser.Password = "xg4*Wv"
9: /// </code>
10: /// </example>
11: public string UserId { get; set; }
The <exception> Tag
The <exception> tag is used to define any exceptions that could be thrown from within the member associated with the current block of XML documentation. Each exception that can be thrown should be defined with its own <exception> block, with an attribute of cref identifying the fully qualified type name of an exception that could be thrown. Note that the Visual Studio 2010 XML comment processor checks the syntax of the exception block to enforce the inclusion of this attribute. It also ensures that you don’t have multiple <exception> blocks with the same attribute value. The full syntax is as follows:
<exception cref="exceptionName">
Exception description.
</exception>
Exception description.
</exception>
Extending the examples from the previous tag discussions, the following code adds two exception definitions to the XML comments associated with the UserId property: System.TimeoutException, and System.UnauthorizedAccessException.
1: /// <summary>
2: /// The <c>UserId</c> property is used in conjunction with other properties
3: /// to setup a user properly. Remember to set the <c>Password</c> field too.
4: /// </summary>
5: /// <exception cref="System.TimeoutException">
6: /// Thrown when the code cannot determine if the user is valid within a reasonable
7: /// amount of time.
8: /// </exception>
9: /// <exception cref="System.UnauthorizedAccessException">
10: /// Thrown when the user identifier is not valid within the current context.
11: /// </exception>
12: /// <example>
13: /// <code>
14: /// myUser.UserId = "daveg"
15: /// myUser.Password = "xg4*Wv"
16: /// </code>
17: /// </example>
18: public string UserId { get; set; }
The <include> Tag
You’ll often have documentation that needs to be shared across multiple projects. In other situations, one person may be responsible for the documentation while others are doing the coding. Either way, the <include> tag will prove useful. The <include> tag enables you to refer to comments in a separate XML file so they are brought inline with the rest of your documentation. Using this method, you can move the actual documentation out of the code, which can be handy when the comments are extensive.
The syntax of <include> requires that you specify which part of the external file is to be used in the current context. The path attribute is used to identify the path to the XML node, and uses standard XPath terminology:
<include file="filename" path="XPathQuery" />
The external XML file containing the additional documentation must have a path that can be navigated with the attribute you specify, with the end node containing an attribute of name to uniquely identify the specific section of the XML document to be included. You can include files in either VB or C# using the same tag. The following code takes the samples used in the <exception> tag discussion and moves the documentation to an external file:
/// <include file="externalFile.xml" path="MyDoc/Properties[@name='UserId']/*" />public string UserId { get; set; }
The external file’s contents would be populated with the following XML document structure to synchronize it with what the <include> tag processing expects to find:
1: <MyDoc>2: <Properties name="UserId">
3: <summary>4: The <c>sender</c> object is used to identify who invoked the procedure.
5: </summary> 6: <summary>7: The <c>UserId</c> property is used in conjunction with other properties
8: to setup a user properly. Remember to set the <c>Password</c> field too. 9: </summary>10: <exception cref="System.TimeoutException">
11: Thrown when the code cannot determine if the user is valid within a
12: reasonable amount of time. 13: </exception>14: <exception cref="System.UnauthorizedAccessException">
15: Thrown when the user identifier is not valid within the current context.
16: </exception> 17: <example> 18: <code>19: myUser.UserId = "daveg"
20: myUser.Password = "xg4*Wv"
21: </code> 22: </example> 23: </Procedures> 24: </MyDoc>For more XML tutorial for XML Documents refer Phase 2 of XML Comments............
