c# - 在 C# 自动实现的属性中定义 和 的目的是什么？

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

正如您所指出的，这两个标签的自动建议内容是多余的。但是，对于记录良好的类，您放置在这两个标记中的文本应该不同，例如作为公共(public) API 的一部分。

例如，让我们看一下 Microsoft 的 DateTime.Date property 的公共(public) 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>

因此您可以看到，工具提示中使用的“摘要”是属性的简短摘要，而“值”是对返回值的更详细描述。

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