TypeName | PropertySummaryDocumentationMustOmitSetAccessorWithRestrictedAccess |
CheckId | SA1624 |
Category | Documentation Rules |
Cause
The documentation text within a C# property’s <summary> tag takes into account all of the accessors within the property, but one of the accessors has limited access.
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 when one of the accessors within the property has limited access (usually the set accessor), but the summary documentation text for the property still refers to both accessors.
Normally, a property’s summary text must begin with wording describing the types of accessors exposed within the property. If the property contains only a get accessor, the summary must begin with the word “Gets”. If the property contains only a set accessor, the summary must begin with the word “Sets”. If the property exposes both a get and set accessor, the summary text must begin with “Gets or sets”.
However, when an accessor within the property is given an access level which is more limited than the access level of the property, this accessor should be omitted from the summary documentation.
It can sometimes be non-obvious whether the set accessor within a property is actually less accessible than the get accessor. For example, consider the case where a public property is contained within an internal class, and the set accessor is given internal accessor. In effect, both the get and set accessors have the same access level. In this case, the summary documentation should refer to both the get and set accessors, since they effectively have the same access level.
In some situations, the set accessor for a property can have more restricted access than the get accessor. For example:
/// <summary>
/// Gets the name of the customer.
/// </summary>
public string Name
{
get { return this.name; }
private set { this.name = value; }
}
1. The set accessor has the same access level as the get accessor. For example:
/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
protected string Name
{
get { return this.name; }
set { this.name = value; }
}
2. The property is only internally accessible within the assembly, and the set accessor also has internal access. For example:
internal class Class1
{
/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
protected string Name
{
get { return this.name; }
internal set { this.name = value; }
}
}
internal class Class1
{
public class Class2
{
/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
public string Name
{
get { return this.name; }
internal set { this.name = value; }
}
}
}
3. The property is private or is contained beneath a private class, and the set accessor has any access modifier other than private. In the example below, the access modifier declared on the set accessor has no meaning, since the set accessor is contained within a private class and thus cannot be seen by other classes outside of Class1. This effectively gives the set accessor the same access level as the get accessor.
public class Class1
{
private class Class2
{
public class Class3
{
/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
public string Name
{
get { return this.name; }
internal set { this.name = value; }
}
}
}
}
4. Whenever the set accessor has protected or protected internal access, it should be referenced in the documentation. A protected or protected internal set accessor can always been seen by a class inheriting from the class containing the property.
internal class Class1
{
public class Class2
{
/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
internal string Name
{
get { return this.name; }
protected set { this.name = value; }
}
}
private class Class3 : Class2
{
public Class3(string name) { this.Name = name; }
}
}
How to Fix Violations
To fix a violation of this rule, update the property’s summary text and remove wording which refers to the limited access accessor.