类属性的 XML 注释的正确语法是什么？
【问题讨论】：
标签： c# xml documentation
应要求提供明确示例，以下摘自 StyleCop 帮助文档“SA1623：PropertySummaryDocumentationMustMatchAccessors”：
属性的摘要文本必须以描述属性中公开的访问器类型的措辞开头。如果该属性仅包含一个 get 访问器，则摘要必须以单词“Gets”开头。如果属性只包含一个集合访问器，那么摘要必须以单词“Sets”开头。如果该属性同时公开了 get 和 set 访问器，则摘要文本必须以“Gets or sets”开头。
例如，考虑以下属性，它公开了 get 和 set 访问器。摘要文本以“Gets or sets”开头。
/// <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; }
}
}
【讨论】：
安装这个：http://submain.com/products/ghostdoc.aspx
右键单击该属性，选择“记录此”。 填空题。
【讨论】：
根据 MSDN link，似乎没有 Class Properties 的官方标签。但是，我会使用这样的东西：
/// <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>
【讨论】：
我建议使用StyleCop。它不仅强制（对我的口味有点强烈）您发表评论，而且还提示您应该如何开始 cmets。
【讨论】：