同时使用的目的和& lt; summary>标记在Visual Studio XML文档中
本文关键字：summary Visual 文档 XML Studio value lt | 更新日期: 2023-09-27 18:08:19
我在VS 2012中使用c#，将XML文档添加到我的代码中，并且我意外地打开了StyleCop规则(SA1609，特别是)，该规则"验证公共或受保护的属性是否包含带有值标记的文档头"。
还有另一条规则(SA1604，这次有意开启)，它"验证文档头是否包含格式正确的摘要标记"。
然而，我正在努力看看你在值标签中放了什么，而这些标签还没有在摘要标签中。目前我的摘要标签都是"获取或设置"之类的。应该在相应的值标签中添加什么来补充它?
(只是为了澄清，我很高兴设置StyleCop -当我不小心打开所有文档规则时，它只是引起了我对value标签的注意)
MSDN对这个没有多大帮助:
- 值标签的页面似乎暗示你应该详细说明支持字段正在使用(这似乎是一个坏主意在信息隐藏的兴趣)。
- 他们的XML指南文档说"一个值标签用于描述属性值"。我甚至不确定这是什么意思——对我来说，这听起来很像总结。
tl;博士
在属性的XML文档中同时使用摘要和值标记有什么意义?如何在不重复的情况下使用它们?
摘要是对属性所能做的事情给出一个总体的概述，而值则描述了从属性中期望得到的值。
下面是MSDN上差异的一个很好的例子:List<T>.IList.IsFixedSize Property
在大多数情况下，摘要标记通常会声明"获取或设置一个值…"Summary:获取一个值，该值指示illist是否具有固定大小。
值:如果illist有固定大小，则为true;否则,假的。在List的默认实现中，此属性总是返回false。
simple:这使得随着代码的发展，更容易使它们保持最新。
我个人认为，当代码必须由其他作者修改时，它增加了一些更有用的信息。