c# - 在 Visual Studio XML 文档中同时使用 和 标签的目的

Question

我在 VS 2012 中使用 C# 工作，将 XML 文档添加到我的代码中，我不小心打开了 StyleCop 规则(特别是 SA1609)，它“验证公共(public)或 protected 属性是否包含文档 header 一个值(value)标签”。

还有另一条规则(SA1604，这次有意启用)，它“验证文档标题是否包含格式正确的摘要标记”。

但是，我很难看到您在值(value)标签中放入了摘要标签中没有的内容。目前我的摘要标签说的是“获取或设置某物”。应该在相应的值标签中放置什么来补充它？

(澄清一下，我很高兴设置 StyleCop - 当我不小心打开所有文档规则时，它只是让我注意到值标签)

MSDN 在这方面帮助不大:

• The value tag's page似乎暗示你应该详细说明正在使用什么backing field(无论如何为了信息隐藏的利益，这似乎是一个坏主意)。
• Their How-To on XML documentation表示“值标记用于描述属性值”。我什至不确定那是什么意思 - 对我来说这听起来很像摘要。

tl;dr

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

Answer 1

摘要是对属性可以做什么的一般概述，而值(value)只是描述，期望从属性中获得什么值(value)。

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

Summary: Gets a value indicating whether the IList has a fixed size.

Value: true if the IList has a fixed size; otherwise, false. In the default implementation of List<T>, this property always returns false.

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