TypeName | PartialElementsMustBeDocumented |
CheckId | SA1601 |
Category | Documentation Rules |
Cause
A C# partial element is missing a documentation header.
Rule Description
C# syntax provides a mechanism for inserting documentation for classes and elements directly into the code, through the use of Xml documentation headers. For an introduction to these headers and a description of the header syntax, see the following article: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx.
A violation of this rule occurs if a partial element (an element with the partial attribute) is completely missing a documentation header, or if the header is empty. In C# the following types of elements can be attributed with the partial attribute: classes, methods.
When documentation is provided on more than one part of the partial class, the documentation for the two classes may be merged together to form a single source of documentation. For example, consider the following two parts of a partial class:
/// <summary>
/// Documentation for the first part of Class1.
/// </summary>
public partial class Class1
{
}
/// <summary>
/// Documentation for the second part of Class1.
/// </summary>
public partial class Class1
{
}
These two different parts of the same partial class each provide different documentation for the class. When the documentation for this class is built into an SDK, the tool building the documentation will either choose to use only one part of the documentation for the class and ignore the other parts, or, in some cases, it may merge the two sources of documentation together, to form a string like: “Documentation for the first part of Class1. Documentation for the second part of Class1.”
For these reasons, it can be problematic to provide SDK documentation on more than one part of the partial class. However, it is still advisable to document each part of the class, to increase the readability and maintainability of the code, and StyleCop will require that each part of the class contain header documentation.
This problem is solved through the use of the <content> tag, which can replace the <summary> tag for partial classes. The recommended practice for documenting partial classes is to provide the official SDK documentation for the class on the main part of the partial class. This documentation should be written using the standard <summary> tag. All other parts of the partial class should omit the <summary> tag completely, and replace it with a <content> tag. This allows the developer to document all parts of the partial class while still centralizing all of the official SDK documentation for the class onto one part of the class. The <content> tags will be ignored by the SDK documentation tools.
How to Fix Violations
To fix a violation of this rule, add or fill-in a documentation header for the element.
For example, the following example shows two parts of a partial class, one containing a <summary> header and another containing a <content> header.
/// <summary>
/// Represents a customer in the database.
/// </summary>
public partial class Customer
{
}
/// <content>
/// Contains auto-generated functionality for the Customer class.
/// </content>
public partial class Customer
{
}