如何記錄類屬性

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