StyleCop 4.3 > StyleCop 4.3 Rules > Documentation Rules > SA1624: PropertySummaryDocumentationMustOmitSetAccessorWithRestrictedAccess

StyleCop 4.3	Send comments on this topic.
SA1624: PropertySummaryDocumentationMustOmitSetAccessorWithRestrictedAccess

Glossary Item Box

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.

For example, consider the following property, which exposes both a get and set accessor. The summary text begins with the words “Gets or sets”.

/// <summary>

/// Gets or sets the name of the customer.

/// </summary>

public string Name

{

get { return this.name; }

set { this.name = value; }

}

If the access level of the set accessor is changed to internal, the summary text must be changed to omit the set accessor. This is because the access level of the set accessor is now more limited than the access level of the overall property. The same applies whenever the access level of an accessor is more limited than the access level of the overall property.

/// <summary>

/// Gets the name of the customer.

/// </summary>

public string Name

{

get { return this.name; }

internal set { this.name = value; }

}

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.