在Visual Studio XML文档中同时使用<value>和<summary>标记的目的

Question

30

我正在使用VS 2012中的C#编程，为我的代码添加XML文档，并意外开启了一个StyleCop规则(SA1609)，该规则“验证公共或受保护属性是否包含具有值标记的文档头”。

还有另一个规则(SA1604，这次是故意打开的)，它“验证文档头是否包含格式正确的摘要标记”。

然而，我很难看出在值标记中应该放什么，因为已经在摘要标记中了。目前，我的摘要标记大致说了“获取或设置某物”。应该在相应的值标记中放置什么来补充它？

（只是为了澄清，我很满意设置StyleCop - 它只是在我意外地打开所有文档规则时引起了我的注意）

MSDN对此并没有太大帮助：

tl;dr

在属性的XML文档中，summary标签和value标签都有什么作用？如何使用它们而不重复自己？

- Philip C

2个回答

0

简单来说，这使得在代码不断演进的过程中更容易保持它们的最新状态。

我个人认为，当代码需要由其他作者进行修改时，这会增加一些有用的信息。

- Santiago Baigorria

4

它是如何使得更新更容易保持最新的？ - Simon Morgan

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- myermian · Accepted Answer

总结是对属性的概述，而值则仅描述该属性应具有的值。

以下是MSDN上差异的良好示例：List<T>.IList.IsFixedSize Property

总结：获取一个值，指示IList是否具有固定大小。

值: 如果IList具有固定大小，则为true；否则为false。在List<T>的默认实现中，此属性始终返回false。

大部分情况下，总结标签通常会说明"获取或设置一个值..." ，而值标签通常会说明预期的值，包括期望的默认值。