TICS Coding Standard Viewer 
TIOBE Software Quality Framework
Print-friendly version
©TIOBE Software www.tiobe.com
 
C# Coding Standard
Search

Rule:  4@106Checked automatically with code checker

Synopsis:Use XML tags for documenting types and members
Language:C#
Severity Level:9
Category:Comments


Description:

All public and protected types, non-trivial methods, fields, events and delegates shall be documented using XML tags. Using these tags will allow IntelliSense to provide useful details while using the types. Also, automatic documentation generation tooling relies on these tags.

Section tags define the different sections within the type documentation.

SECTION TAGSDESCRIPTIONLOCATION
<summary>Short descriptiontype or member
<remarks>Describes preconditions and other additional information.type or member
<param>Describes the parameters of a methodmethod
<returns>Describes the return value of a methodmethod
<exception>Lists the exceptions that a method or property can throwmethod, even or property
<value>Describes the type of the data a property accepts and/or returnsproperty
<example>Contains examples (code or text) related to a member or a typetype or member
<seealso>Adds an entry to the See Also sectiontype or member
<overloads>Provides a summary for multiple overloads of a methodfirst method in a overload list.

Inline tags can be used within the section tags.

INLINE TAGSDESCRIPTION
<see>Creates a hyperlink to another member or type
<paramref>Creates a checked reference to a parameter

Markup tags are used to apply special formatting to a part of a section.

MARKUP TAGSDESCRIPTION
<code>Changes the indentation policy for code examples
<c>Changes the font to a fixed-wide font (often used with the <code> tag)
<para>Creates a new paragraph
<list>Creates a bulleted list, numbered list, or a table
<b>Bold typeface
<i>Italics typeface

Exception:

In an inheritance hierarchy, do not repeat the documentation, but use the <see> tag to refer to the base class or interface member.