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

最佳答案

为了响应对明确示例的请求，以下摘录来自 StyleCop 帮助文档“SA1623:PropertySummaryDocumentationMustMatchAccessors”:

属性的摘要文本必须以描述属性中公开的访问器类型的措辞开头。如果该属性只包含一个 get 访问器，则摘要必须以单词“Gets”开头。如果该属性仅包含一个集合访问器，则摘要必须以单词“集合”开头。如果该属性公开了 get 和 set 访问器，则摘要文本必须以“Gets or sets”开头。

例如，考虑以下属性，它公开了 get 和 set 访问器。摘要文本以“获取或设置”一词开头。

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

如果该属性返回 bool 值，则应用附加规则。 bool 属性的摘要文本必须包含单词“获取一个值指示是否”、“设置一个值指示是否”或“获取或设置一个值指示是否”。例如，考虑以下 bool 属性，它只公开一个 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 访问器已被授予私有(private)访问权限，这意味着它只能由包含它的类的本地成员访问。但是，get 访问器从父属性继承其访问权限，因此任何调用者都可以访问它，因为该属性具有公共(public)访问权限。

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

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

确定是否在属性的摘要文档中包含 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.该属性是私有(private)的或包含在私有(private)类下，并且 set 访问器具有除 private 之外的任何访问修饰符。在下面的示例中，在 set 访问器上声明的访问修饰符没有任何意义，因为 set 访问器包含在私有(private)类中，因此不能被 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.每当设置访问器具有 protected 或 protected 内部访问时，应在文档中引用它。从包含属性的类继承的类始终可以看到 protected 或 protected 内部集访问器。

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

关于c# - 如何记录类属性，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/3942960/