c# - 使用两者的目的和Visual Studio XML 文档中的标记

Question

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

还有另一条规则（SA1604，这次特意打开），“验证文档标题是否包含格式正确的摘要标记”。

但是，我很难看到您在 value 标签中放入的内容尚未在 summary 标签中。目前我的摘要标签说的是“获取或设置某些东西”。应该在相应的值标签中添加什么来补充它？

（澄清一下，我对设置 StyleCop 很满意——当我不小心打开了所有文档规则时，它只是引起了我对 value 标签的注意）

MSDN 对这个帮助不大：

• 值标签的页面似乎暗示您应该详细说明正在使用的支持字段（无论如何，这对于隐藏信息而言似乎是个坏主意）。
• 他们的 How-To on XML 文档说“使用值标签来描述属性值”。我什至不确定这意味着什么——这听起来很像我的总结。

tl;博士

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

Answer 1

摘要是对属性可以做什么的一般概述，而值仅描述了该属性的期望值。

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

摘要：获取一个值，该值指示 IList 是否具有固定大小。

值：如果 IList 具有固定大小，则为 true；否则为假。在 List<T> 的默认实现中，此属性始终返回 false。

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

Answer 2

简单地说：这使得随着代码的发展更容易使它们保持最新。

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