在Visual Studio XML文档中使用<value>和<summary>标记的目的</summary> </value>

Question

我在VS 2012中使用C＃，在我的代码中添加了XML文档，并且我不小心打开了StyleCop规则（特别是SA1609），该规则“验证公共或受保护的属性是否包含文档标题值标签“。

还有另一条规则（SA1604，此次故意启用），“验证文档标题包含格式正确的摘要标记”。

然而，我很难看到您在摘要标记中尚未包含的值标记。目前我的摘要标签说的是“获取或设置某些东西”。应该在相应的值标签中添加什么来补充它？

（只是为了澄清一点，我很高兴设置StyleCop - 它只是在我意外打开所有文档规则时引起了我对值标记的注意）

MSDN对这个问题的帮助不大：

• The value tag's page似乎暗示你应该详细说明正在使用支持字段（为了信息隐藏，这似乎是个坏主意。）
• Their How-To on XML documentation表示“值标记用于描述属性值”。我甚至不确定这意味着什么 - 这听起来很像我的摘要。

TL;博士

在属性的XML文档中同时包含摘要和值标记有什么意义？如何在不重复自己的情况下使用它们？

Answer 1

摘要是概述属性可以做什么，而值只是描述了属性的期望值。

以下是MSDN上差异的一个很好的例子：List<T>.IList.IsFixedSize Property

  

摘要：获取一个值，该值指示IList是否具有固定大小   
  值：如果IList具有固定大小，则为true;否则，错误。在List＆lt; T＆gt;的默认实现中，此属性始终返回false。

在大多数情况下，摘要标记通常会声明“获取或设置值...”，而值标记通常会说明期望的值，包括预期的默认值是

Answer 2

简单地说：随着代码的发展，这样可以更容易地使它们保持最新状态。

我个人认为，当代码必须由其他作者修改时，它会添加一些更有用的信息。