如何记录类属性

Question

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

Answer 1

安装此：http://submain.com/products/ghostdoc.aspx

的财产，选择 '文档本' 单击鼠标右键。 填空。

Answer 2

根据MSDN，link，它看起来没有类属性的官方标签。但是，我会用这样的：

/// <summary>Here is an example of a propertylist: 
/// <list type="Properties"> 
/// <item> 
/// <description>Property 1.</description> 
/// </item> 
/// <item> 
/// <description>Property 2.</description> 
/// </item> 
/// </list> 
/// </summary> 

Answer 3

我建议使用StyleCop。它不仅强制（对我的口味有点强烈）你评论，但也给你一个暗示应该如何开始评论。

Answer 4

为了应对显式实例的请求，下面的提取物是从了StyleCop帮助文档，“SA1623：PropertySummaryDocumentationMustMatchAccessors”：

酒店的摘要文本必须以文字开始描述中暴露的类型存取方法属性。如果该属性只包含一个get访问器，则摘要必须以单词“Gets”开头。如果该属性只包含一个设置访问器，则摘要必须以“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访问具有比其他私人任何访问修饰符。在下面的示例中，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.每当set访问器保护或保护内部访问时，应该在文档中引用它。受保护或受保护的内部集合访问器始终可以被从包含该属性的类继承的类看到。

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