Summary

The summary succinctly states what a type or member does or represents. All types and members must have summaries, consisting of a short description (optimally one sentence) that conveys the importance of the class or member.

Guidelines

Begin with a present-tense, third-person verb, except for exception classes, enum members, abstract members, and virtual members (see the links in the next section).

• Do not merely repeat the wording of the member name in the summary; provide a meaningful description and context. For example, instead of describing the String.Format method by saying Formats a string, you can use a description like this: Replaces each format item in a specified string with the string representation of a specified object.
• Use programming language-neutral text. For example, don't include Visual Basic or C#-specific terms in your summary.
• Avoid using special formatting such as lists that might cause problems for IntelliSense builds.
• Avoid using parameter names or self-referential type or member names in the summary. There are exceptions; for example, you can use the type name in summaries for constructors and for dispose methods.
• For overloaded constructors and methods, provide a general summary that is broad enough to apply to all the overloads, and write more specific summaries for the individual overloads. For the individual overloads, use wording that differentiates each overload from the others, and provide enough information to help users select the overload they'd like to call.

Wording for specific types and members

The wording for Summary sections varies according to the type or member that you're documenting, as described in these sections:

• Class
• Constructor
• Enum
• Event-related
• Field
• Abstract and virtual member
• Method
• Operator
• Property
• Overloaded member