在 C# 自动实现的属性中同时定义 <summary> 和 <value> 的目的是什么？

Question

C# 规范/StyleCop（不确定是哪个）建议使用两个标签来注释自动属性——<summary> 和 <value>，给出如下内容：

class Foo
{
    /// <summary>Gets bar.</summary>
    /// <value>Bar.</value>
    public Example Bar { get; set; }
}

但出于所有实际目的，<summary> 的值始终为Gets <whatever you said for value here\>.

这里的单独标签是为了帮助特定的文档生成器，还是与编译器标记自动属性的方式有关，或者其他什么？

Answer 1

正如您所指出的，这两个标签的自动建议内容是多余的。 但是，对于一个有据可查的类（例如作为公共 API 的一部分），您在这两个标签中放置的文本应该是不同的。

例如，让我们看一下 Microsoft 针对 DateTime.Date property 的公共 API 文档。

注释中的<summary> 和<value> 标签对应于文档的两个不同部分。在这种情况下，文档可能是从如下评论生成的：

/// <summary>
///   Gets the date component of this instance.
/// </summary>
/// <value>
///   A new object with the same date as this instance, and the time value
///   set to 12:00:00 midnight (00:00:00).
/// </value>

所以你可以看到，在tooltips中使用的“summary”是属性的缩写摘要，而“value”是对返回值的更详细的描述。

阅读<summary> 和<value> 标签的完整文档了解更多详情。