SA1623.md

SA1623

TypeName	SA1623PropertySummaryDocumentationMustMatchAccessors
CheckId	SA1623
Category	Documentation Rules

Cause

The documentation text within a C# property's <summary> tag does not match the accessors within the property.

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:https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments.

A violation of this rule occurs if a property's summary documentation does not match the accessors within the property.

The property's summary text should begin with wording describing the types of accessors exposed within the property. If the property contains only a get accessor, the summary should begin with the word "Gets". If the property contains only a set accessor, the summary should begin with the word "Sets". If the property exposes both a get and set accessor, the summary text should begin with "Gets or sets".

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 property returns a Boolean value, an additional rule is applied. The summary text for Boolean properties should contain the words "Gets a value indicating whether", "Sets a value indicating whether", or "Gets or sets a value indicating whether". For example, consider the following Boolean property, which only exposes a get accessor:

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled
{
    get { return this.enabled; }
}

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; }
}

In this example, the set accessor has been given private access, meaning that it can only be accessed by local members of the class in which it is contained. The get accessor, however, inherits its access from the parent property, thus it can be accessed by any caller, since the property has public access.

In this case, the documentation summary text should avoid referring to the set accessor, since it is not visible to external callers.

StyleCop applies a series of rules to determine when the set accessor should be referenced in the property's summary documentation. In general, these rules require the set accessor to be referenced whenever it is visible to the same set of callers as the get accessor, or whenever it is visible to external classes or inheriting classes.

The specific rules for determining whether to include the set accessor in the property's summary documentation are:

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 so that the description begins with the proper wording, depending upon the type of the property and the types of accessors within the property.

How to suppress violations

[SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1623:PropertySummaryDocumentationMustMatchAccessors", Justification = "Reviewed.")]

#pragma warning disable SA1623 // PropertySummaryDocumentationMustMatchAccessors
#pragma warning restore SA1623 // PropertySummaryDocumentationMustMatchAccessors