Predefined XML Tags for Documentation Comments

appendix
B
Predefined XML Tags for
Documentation Comments
T
his appendix presents a subset of the predefined XML tags that are most useful for
C# program documentation. All tags must be preceded by the /// comment.
XML Tag Meaning and Example
<c> Describes a line of code.
<c>int i = 10;</c>
<code> Describes multiple lines of code.
<code> CodeSample </code>
<example> Describes the code sample.
<example> Description </example>
<exception> Describes which exceptions a class can throw.
<exception cref="type"> Description </exception>
<exception cref="System.Exception"> Thrown when... </exception>
<include> Includes comments from another documentation file.
<include file=‘filename’ path=‘tagpath[@name="id"’/>
<include file=‘Class.doc’ path=‘Doc/Prj[@name="Class"]/*’/>
Table B.1: Predefined XML tags for documentation comments.
241
242
Appendix B: Predefined XML Tags for Documentation Comments
■
XML Tag Meaning and Example
<list> Inserts a list into the documentation.
<list type="bullet" | "number" | "table">
<listheader>
<term> Name </term>
<description> Description </description>

</listheader>
<item>
<term> Name </term>
<description> Description </description>
</item>
</list>
<para> Sets off the text as a paragraph.
<para> Text </para>
<param> Describes a given parameter.
<param name="name"> Description </param>
<param name="n"> The specified integer value. </param>
<paramref> Associates a given XML tag with a specified parameter.
<paramref name="name"/>
The <paramref name="n"/> parameter specifies an integer value.
<permission> Describes the access permission of a member.
<permission cref="type"> Description </permission>
<permission cref="MyClass.MyMethod"> Public access.</permission>
<remarks> Describes the type of a given member.
<remarks> Description </remarks>
<returns> Describes the return value.
<returns> Description </returns>
<see> Provides a cross-reference to related elements available to
the current compilation environment.
<see cref="element"/>
<see cref="MyClass.MyMethod"/>
<seealso> Same as the <see> tag except it emits a separate "see also" section.
<summary> Describes a given class or member.
<summary> Description </summary>
<value> Describes a given property.
<value> Description </value>

Table B.1: (continued)
References
References on C#, XML, and .NET Specifications
ECMA-334 C# Language Specification (First Edition), ,
December 2001.
ECMA-334 C# Language Specification (Second Edition), ,
December 2002.
ECMA/TC39-TG2 C# Language Specification (Working Draft 2.7),
, June 2004.
Microsoft C# Version 1.2 Language Specification, Microsoft Corporation, June 2003.
Microsoft C# Version 2.0 Language Specification, Microsoft Corporation, May 2004.
ECMA-335 Common Language Infrastructure (First Edition),
, December 2001.
W3C Extensible Markup Language (XML) 1.0, February 2004.
Microsoft .NET Framework Standard Library Annotated Reference, Volume 1: Base Class
Library and Extended Numerics Library, Microsoft .NET Development Series, Addison-
Wesley Professional, June 2004.
References on Object-Oriented Design
Martin Fowler, Refactoring: Improving the Design of Existing Code, Addison-Wesley, 1999.
Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides, Design Patterns: Elements of
Reusable Object-Oriented Software, Addison-Wesley, 1995.
243
244
References
■
Bertrand Meyer, Object-Oriented Software Construction (2nd Edition), Prentice-Hall, 1997.
John Vlissides, Pattern Hatching: Design Patterns Applied, Addison-Wesley, 1998.
Related Web Sites
/>The official ECMA C# language specification site.
/>The official Microsoft .NET developers site.

/>The official Microsoft Visual C# language site.

The Microsoft .NET Framework community support site.
Index
Abstract classes
declaring, 136–137
EBNF definition of, 136
FileStream, 190–191
implementing, 137–138
reference types of,
136–138
Stream, 190
using, 138
Abstract property, 151–153
Access modifiers
classes with, 12–14
compilation with, 24–26
encapsulation with, 13
information hiding with, 13
protected method with, 13
public v. private in, 12–13
Accessors
get, 150–151
indexers as, 155–157
restrictive accessibility for,
155t
set, 150–151
Additive operators,
98–99, 98t
Aggregation

class, 45, 46
inheritance v., 50–51
use of, 46
Alive threads, 198–200
Arithmetic operators, 97–101,
97t, 98t, 101t
additive, 98–99, 98t
binary additive, 98–99, 98t
checked/unchecked,
99–100
compound, 100–101, 101t
multiplicative, 97–98, 97t
Arrays. See also Indexers
accessing, 78
collections v., 76–77
creating, 77–78
initializing, 77–78
jagged, 78–79
rectangular, 78–79
unified type system with,
76–79
as, type testing with, 95–96
Assemblies, reflection
accessing, 212–215
Assignment operators, 84–86
compound arithmetic,
100–101, 101t
compound logical, 90t,
91–92
compound shift, 97, 97t

multiple, 86
references in, 85
simple, 84–85
Associativity
left, 84
operator, 83–84, 84t
right, 84
rules of, 84, 84t
Attributes, 211, 215–223
AttributeTargets method
with, 219
conditional compilation
with, 217
EBNF definition of, 215–216
exception serialization
with, 216–217
extracting, 221–223
.NET with, 211, 215–216
obsolete code with, 218
reflection with, 221–223
user-defined, 218–220
AttributeTargets method, 219
Base keyword, class with,
47–48
Binary additive operators,
98–99, 98t
Binary streams, input/output
with, 188–189
Bitwise operators. See Logical
operators

Block statements, 107–108
EBNF definition of, 107
Boolean, literals, 63
Boolean expression. See
Conditional operators
Boxing, unified type system
with, 66–67
Break statements, 115
Bubbling up exceptions, 122
Byte streams, input/output
with, 190–191
Casting. See Boxing
Character, literals, 63
Character streams,
input/output with,
191–192
Checked operators, 99–100
overflow error with, 99–100
Checked statements, 116
245