如何记录类属性

Question

类属性的XML注释的正确语法是什么？

Answer 1

在响应显式示例请求时,以下摘录来自StyleCop帮助文档"SA1623:PropertySummaryDocumentationMustMatchAccessors":

属性的摘要文本必须以描述属性中公开的访问者类型的措辞开头.如果属性仅包含get访问器,则摘要必须以单词"Gets"开头.如果属性仅包含set访问器,则摘要必须以"Sets"一词开头.如果属性公开get和set访问器,则摘要文本必须以"获取或设置"开头.

例如,请考虑以下属性,该属性公开get和set访问器.摘要文本以"获取或设置"开头.

/// <summary>
/// Gets or sets the name of the customer. 
/// </summary>
public string Name
{
    get { return this.name; }
    set { this.name = value; }
}

如果属性返回布尔值,则应用其他规则.布尔属性的摘要文本必须包含单词"获取指示是否为的值","设置指示是否为"的值,或"获取或设置指示是否为"的值.例如,请考虑以下布尔属性,该属性仅公开get访问器:

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

在某些情况下,属性的set访问器可以具有比get访问器更多的访问限制.例如:

/// <summary>
/// Gets the name of the customer. 
/// </summary>
public string Name
{
    get { return this.name; }
    private set { this.name = value; }
}

在此示例中,set访问器已被授予私有访问权限,这意味着它只能由包含它的类的本地成员访问.但是,get访问器从父属性继承其访问权限,因此任何调用者都可以访问它,因为该属性具有公共访问权限.

在这种情况下,文档摘要文本应避免引用set访问器,因为外部调用者看不到它.

StyleCop应用一系列规则来确定何时应在属性的摘要文档中引用set访问器.通常,这些规则要求set访问器在与get访问器相同的一组调用者可见时,或者只要外部类或继承类可见,就会被引用.

确定是否在属性摘要文档中包含set访问器的具体规则是:

1. set访问器具有与get访问器相同的访问级别.例如:

/// <summary>
/// Gets or sets the name of the customer. 
/// </summary>
protected string Name
{
    get { return this.name; }
    set { this.name = value; }
}

2.该属性仅在程序集内部可访问,并且set访问器也具有内部访问权限.例如:

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.属性是私有的或包含在私有类下面,set访问器具有除private之外的任何访问修饰符.在下面的示例中,在set访问器上声明的访问修饰符没有意义,因为set访问器包含在私有类中,因此Class1之外的其他类不能看到它.这有效地为set访问器提供了与get访问器相同的访问级别.

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.无论何时设置访问者具有受保护或受保护的内部访问权限,都应在文档中引用.继承自包含该属性的类的类始终可以看到受保护或受保护的内部集访问器.

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