Visual Studio 禁用缺少 XML 注释警告答案

【问题标题】：Visual Studio Disabling Missing XML Comment WarningVisual Studio 禁用缺少 XML 注释警告
【发布时间】：2011-11-02 15:03:25
【问题描述】：

我有一个项目有超过 500 个Missing XML Comment 警告。我知道我可以删除 XML 注释功能，或将空注释 sn-ps 粘贴到任何地方，但我更喜欢通用解决方案，我可以进行一项更改以禁用所有此类警告。

我刚才做的是放

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

或

#pragma warning disable 1591

只是好奇是否有可能。

【问题讨论】：

真正的问题是什么？您想知道另一种禁用 XML cmets 丢失时生成的警告的方法吗？在项目的属性中更改为“构建”选项卡并取消选中“XML 文档文件”。但是，我建议不要抑制警告，而是添加缺少的文档。
那是绝对正确的，但我只是好奇我们是否可以从一个地方解决这个问题，因为我是新手。
这些相关问题可能会有所帮助：stackoverflow.com/questions/11444631/…stackoverflow.com/questions/3630282/…
只有对其他程序集可见的成员才会出现警告。人们经常无缘无故地创建类（和接口、枚举等）public。在这种情况下，一个简单的（并且在我看来很好）的解决方法是从最外层的封闭类型中删除单词public（或用多余的internal 关键字替换它，具体取决于首选样式）。然后所有关于此类型及其成员的 CS1591 警告都会消失。当然，您可能仍然需要保留一些类型 public。但在这种情况下，您需要正确记录他们的公共部分是公平的。

标签： visual-studio-2010 xml-comments

【解决方案1】：

如上所述，总的来说，我认为不应忽略（禁止）这些警告。总而言之，绕过警告的方法是：

通过更改项目来抑制警告Properties > Build > Errors and warnings > Suppress warnings 通过输入 1591
添加 XML 文档标签（GhostDoc 非常方便）
通过编译器选项抑制警告
取消选中项目Properties > Build > Output 中的“XML 文档文件”复选框
在相应文件的顶部添加#pragma warning disable 1591，在底部添加#pragma warning restore 1591

【讨论】：

请不要使用 GhostDoc。如果可以从方法名称中推断出注释，则人类可以更好地推断出注释。这增加了零值。最好把时间花在祝贺自己找到了一个名副其实的方法。
我不同意，GhostDoc 帮助我快速添加所需的参数列表和返回标签（如果方法不是 void）。我确实使用并喜欢它，而且我认识很多其他人也这样做。然而，确实，摘要中的描述可能需要进行一些编辑，但在这种情况下，这对于大多数自动现象都很重要。
如果它所做的只是添加占位符，那将是一个很好的节省时间的方法，但是我看到开发人员留下生成文本的代码库数量让我们认为我们还不够成熟使用它。注释是非自我记录代码的（通常是必要的）拐杖，并且通过提供快捷方式，该工具对世界代码产生了负面的净收益。
@JRoughan：我完全同意。最糟糕的是，当您终于有时间正确记录您的代码时，这些工具使您无法判断您的真实文档覆盖范围有多彻底。任何计算文档覆盖率的工具都将始终读取 100%。因此，您实际上必须完成阅读每个 XML 注释并评估是否足以记录代码的费力工作。在一个大型项目上完成了这个，我可以告诉你，这根本不好玩。请人！不要使用这些自动文档工具！
@Gorgsenegger：在这种情况下不是。有缺陷的不是工具，而是整个概念。如果您想要的话，VS2012 会向标准化 XML cmets 添加方法/参数存根。但是添加只是方法名称的较长版本的 cmets 并将其称为文档只是视觉上的混乱。

【解决方案2】：

禁用警告：转到项目属性（右键单击您的项目并从上下文菜单中选择属性）转到构建选项卡

将 1591 添加到抑制警告文本框

【讨论】：

像逗号分隔列表的魅力一样工作：“S125,CS1591,S1172”。构建后，warings 消失了。
感谢您回答问题，而不是就是否取消警告进行演讲！

【解决方案3】：

您还可以修改项目的.csproj 文件，在第一个<PropertyGroup> 中包含<noWarn>1591</noWarn> 标记。原文来自Alexandru Bucur's Article Here

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

【讨论】：

这应该是当前的答案。
同意。大多数答案不适用于其他编辑器，例如 Visual Studio Code。

【解决方案4】：

进入项目属性并取消选中生成 XML 文档选项。

重新编译，警告应该会消失。

【讨论】：

这是一个很好的方法，只要您不需要生成 XML 文档并且您不介意 XML cmets 不会被验证。
如果您想保留来自非自动生成的文件的警告，这不起作用。删除所有警告只是为了摆脱一部分警告对我来说似乎有点矫枉过正。此外，在大多数公司中，通常的做法是在所有不包含自动生成代码的文件中实际创建 XML cmets。此外，用户要求的解决方案不会简单地删除 XML 注释功能，因此无法回答问题。
这帮助我弄清楚了为什么我会收到有关 XML cmets 被禁用的警告，因此我可以通过选中该框来修复它，基本上与此答案所说的相反。

【解决方案5】：

这本来是一条评论，但我无法让它适应限制：

我希望仅为 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

真的没有办法自动做到这一点吗？每次自动生成的代码覆盖文件时，您都必须重做。

【讨论】：

我认为这个警告不应该出现在自动生成的内容中，也许你必须检查项目属性中的相应设置。
不，这一切都是通过启用 XML-Comment 警告来显示的。并且没有这样的选项可以仅为自动生成的代码禁用它。因此，当您需要重新生成代码时会被剪掉。
在项目属性Code Analysis下，有一个选项Supress results from generated code。每次代码重新生成后必须重新运行宏并不是真正的解决方案 IMO。如果上面的选项对您不起作用，也许可以调整代码生成器以自动添加 pragma 指令？
@Laoujin 感谢您的评论，但正如我所提到的，我也不喜欢这个解决方案。我看不出拒绝投票的原因，我使用了您提到的设置但没有成功。您有机会尝试 WebService 导入的解决方案吗？

【解决方案6】：

Visual Studio 2022：

我建议在 Visual Studio 中使用 .editorconfig 文件来设置所有解决方案的通用代码样式。

在这种情况下，只需将此代码手动添加到.editorconfig 文件中：

# SA0001: XML comment analysis is disabled due to project configuration
dotnet_diagnostic.SA0001.severity = none

注意：对我来说，从编辑器配置设计器中抑制 SA0001 不起作用。

文件中只有手动设置规则。

【讨论】：