Visual Studio禁用缺少的XML注释警告


198

我有一个带有500多个Missing XML Comment警告的项目。我知道我可以删除XML注释功能,或将空的注释片段粘贴到任何地方,但是我更喜欢一种通用解决方案,在该解决方案中我可以进行更改以禁用此类型的所有警告。

我刚才所做的就是

///<Summary>
/// 
///</Summary>

要么

#pragma warning disable 1591

只是好奇是否有可能。


3
实际问题是什么?您是否想知道另一种禁用XML注释丢失时生成的警告的方法?在项目的属性中,更改为“构建”选项卡,然后取消选中“ XML文档文件”。但是,我建议不要隐藏警告,而是添加缺少的文档。
Gorgsenegger 2011年

那是绝对正确的,但只是因为我刚接触这一点而对如何才能从一个地方解决这个问题感到好奇。
Nivid Dholakia 2011年


1
仅对其他程序集可见的成员显示警告。人们通常public没有充分的理由制作类(以及接口,枚举等)。在这种情况下,一个简单(并且我认为很好)的解决方案是仅从最外面的封闭类型中删除单词public(或internal根据需要的样式将其替换为冗余关键字)。然后,有关此类型及其成员的所有CS1591警告均消失。当然,您可能仍然必须保留某些类型public。但是在那种情况下,您需要正确记录其公共部分是很公平的。
杰普·斯蒂格·尼尔森

Answers:


318

如上所述,总的来说,我不认为这些警告应该被忽略(抑制)。总而言之,警告的解决方法是:

  • 通过改变项目取消警告Properties> Build> Errors and warnings> Suppress warnings输入1591
  • 添加XML文档标签(GhostDoc可以非常方便地使用)
  • 通过编译器选项抑制警告
  • 取消选中“XML文档文件”复选框项目Properties> Build>Output
  • 添加#pragma warning disable 1591在各自的文件的顶部和#pragma warning restore 1591底部

178
请,请不要使用GhostDoc。如果可以从方法名称推断出注释,那么人类可以更好地推断出注释。这将增加零值。最好把时间花在祝贺自己使用著名的方法上。
JRoughan 2012年

24
我不同意,GhostDoc帮助我快速添加所需的参数列表和一个返回标记(如果该方法不是无效的)。我确实喜欢并喜欢它,而且我认识很多其他也喜欢它的人。但是,确实可以对摘要中的描述进行一些编辑,但这对于这种情况下的大多数自动操作而言很重要。
Gorgsenegger

32
如果做的只是添加占位符,那将是一个节省时间的好方法,但是我看到开发人员将生成的文本保留在其中的代码库数量,使我们认为我们还不够成熟,无法使用它。对于不是自我记录的代码,注释是(通常是必要的)拐杖,并且通过提供快捷方式,此工具对整个世界的代码都有负面的净收益。
JRoughan

25
@JRoughan:我完全同意。最糟糕的是,当您终于有时间适当地编写代码文档时,这些工具将使您无法分辨出真正文档的覆盖范围。任何计算文档覆盖率的工具都将始终读取100%。因此,从字面上看,您必须完成精疲力尽的任务,即读取每个 XML注释并评估是否足以编写代码。我已经在一个大型项目上完成了这一步,我可以告诉你,这一点都不好玩。请人!不要使用这些自动文档编制工具!
HiredMind 2012年

36
@Gorgsenegger:在这种情况下不是。有缺陷的不是工具,而是整个概念。VS2012如果需要的话,可以将方法/参数存根添加到标准化的XML注释中。但是添加只是方法名称的较长版本的注释并称为文档只是视觉上的混乱。
HiredMind

74

禁用警告:转到项目属性(右键单击您的项目,然后从上下文菜单中选择“属性”)。转到“生成”选项卡 在此处输入图片说明

将1591添加到“禁止警告”文本框中 在此处输入图片说明


4
就像一个带有逗号分隔列表的超级按钮一样工作:“ S125,CS1591,S1172”。建立之后,警告消失了。
AFD

9
感谢您回答问题,而不是就是否禁止警告发表意见!
Dal

31

您还可以修改项目的.csproj文件,以<noWarn>1591</noWarn>在第一个文件中包含一个标记<PropertyGroup>。最初来自Alexandru Bucur在这里的文章

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    ...
    <NoWarn>1591</NoWarn>
  </PropertyGroup>
  ...
</Project>

3
这应该是当前的烦恼。
Edgar Salazar

3
同意 大多数答案不适用于其他编辑器,例如Visual Studio Code。
Krzysztof Czelusniak

9

进入项目属性,然后取消选中“生成XML文档”选项。

取消选中XML文档文件

重新编译,警告应该消失。


2
只要您不需要生成XML文档并且您不介意XML注释不会得到验证,这就是一个好方法。
基思

1
如果要保留未自动生成的文件中的警告,则此方法不起作用。对我来说,删除所有警告只是为了摆脱一些警告似乎有些过头。此外,在大多数公司中,通常的做法是在所有不包含自动生成的代码的文件中实际创建XML注释。另外,用户要求的解决方案不能简单地删除XML注释功能,因此不能回答问题。
SubliemeSiem 2015年

4

这本来是评论,但我无法满足要求:

我想仅针对Reference.cs和WebService导入禁用它们。实际上,我正在使用宏来为文件执行此操作。只需打开文件并执行此宏即可(在VS2010中测试):

Sub PragmaWarningDisableForOpenFile()
    DTE.ActiveDocument.Selection.StartOfDocument()
    DTE.ActiveDocument.Selection.NewLine()
    DTE.ActiveDocument.Selection.LineUp()
    DTE.ActiveDocument.Selection.Insert("#pragma warning disable 1591")
    DTE.ActiveDocument.Selection.EndOfDocument()
    DTE.ActiveDocument.Selection.NewLine()
    DTE.ActiveDocument.Selection.Insert("#pragma warning restore 1591")
    DTE.ActiveDocument.Save()
End Sub

真的没有办法自动执行此操作吗?每次自动生成的代码覆盖文件时,您都必须重做一次。


2
我认为不应针对自动生成的内容显示此警告,也许您必须检查项目属性中的相应设置。
Gorgsenegger

1
不,仅通过启用XML-Comment警告就可以显示所有内容。而且没有这样的选项可以仅针对自动生成的代码禁用它。因此,当您需要重新生成代码时,就会被删除。
Kjellski

在项目属性下Code Analysis,有一个选项Supress results from generated code。每次代码重新生成后都必须重新运行宏并不是IMO的解决方案。如果上面的选项对您不起作用,也许可以将代码生成器调整为自动添加pragma指令?
Laoujin 2013年

@Laoujin感谢您的评论,但是正如我提到的那样,我也不喜欢这种解决方案。我看不出投票率下降的原因,我使用了您提到的设置,但没有成功。您是否有机会尝试使用WebService导入解决方案?
Kjellski
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.