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

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

例如，让我们看一下 Microsoft 的DateTime.Date 属性的公共 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>标记的完整文档以了解更多详细信息。