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>

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

阅读<summary>和<value>标记的完整文档以获取更多详细信息。

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

1 个答案: