Visual Studio禁用缺失XML注释警告

Question

我有一个项目，有超过500个“Missing XML Comment”警告。我知道我可以删除XML注释功能，或者粘贴空的注释片段到各个地方，但我更希望有一个通用解决方案，可以进行一次更改以禁用所有此类型的警告。

目前我所做的是：

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

或者

#pragma warning disable 1591

我只是好奇是否可能实现。

- Nivid Dholakia

---

实际问题是什么？您是否想知道另一种禁用缺少XML注释时生成的警告的方法？在项目属性中切换到“生成”选项卡并取消选中“XML文档文件”。但是，建议不要抑制警告，而是添加缺少的文档。 - Gorgsenegger

这完全正确，只是我很好奇我们是否可以从一个地方解决这个问题，因为我对此还很陌生。 - Nivid Dholakia

这些相关问题可能会有所帮助：https://dev59.com/0mgu5IYBdhLWcg3wRlH0https://dev59.com/HHA65IYBdhLWcg3wyh57 - Mightymuke

警告仅适用于对其他程序集可见的成员。通常人们会将类（以及接口、枚举等）设为“public”，但实际上并没有充分的理由。在这种情况下，一个简单（而且我认为是好的）解决方法就是从最外层封闭类型中删除“public”关键字（或者根据首选样式替换为多余的“internal”关键字）。然后所有有关此类型及其成员的CS1591警告都将消失。当然，您可能仍然需要保持某些类型为“public”。但在这种情况下，要求您正确记录其公共部分是公平的。 - Jeppe Stig Nielsen

Answer 1

如上所述，我认为一般来说不应该忽略（抑制）这些警告。总结一下，避免警告的方法有：

• 通过更改项目 属性 > 生成 > 错误和警告 > 抑制警告 并输入1591来抑制警告
• 添加 XML 文档标记（使用GhostDoc 工具可能会很方便）
• 通过编译器选项来抑制警告
• 在项目 属性 > 生成 > 输出 中取消选中“XML 文档文件”复选框
• 在对应文件顶部添加 #pragma warning disable 1591，在底部添加 #pragma warning restore 1591

- Gorgsenegger

---

请不要使用GhostDoc。如果一个注释可以从方法名中推断出来，人类可以更好地推断出来。这没有任何价值。那段时间最好花在庆祝命名得当的方法上。 - JRoughan

我不同意，GhostDoc可以帮助我快速添加必要的参数列表和返回标记（如果方法不是void）。 我使用并喜欢它，我也知道很多其他人也这样做。 但是，总结中的描述可能需要一些编辑，但这适用于大多数自动化情况。 - Gorgsenegger

如果它只是添加了占位符，那么它将成为一个不错的小工具，但是我曾经看到过很多代码库，开发人员并未删除生成的文本，这让我觉得我们还没有共同足够成熟来使用它。注释对于不自描述的代码是（经常必要的）救命稻草，而通过提供快捷方式，这个工具对世界代码的负面净效益。 - JRoughan

@JRoughan说：“我完全同意。最糟糕的是，当你终于有时间来适当地记录你的代码时，这些工具会使你无法知道你真正的文档覆盖范围有多全面。任何计算文档覆盖率的工具都会读取100％，因此您必须逐个阅读每个 XML注释，并评估其是否足以记录代码。我曾在一个大项目上做过这个，我可以告诉你，这一点也不好玩。请大家！不要使用这些自动文档工具！” - HiredMind

在这种情况下不是工具出了问题，而是整个概念有问题。如果您需要的话，VS2012会将方法/参数桩添加到标准化XML注释中。但添加那些只是方法名称的更长版本，并称其为文档，这只会造成视觉混乱。 - HiredMind

Answer 2

关闭警告： 进入项目属性（右键单击项目并从上下文菜单中选择“属性”） 切换到“构建”选项卡

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

- Rao Adnan

---

逗号分隔的列表可以很好地工作："S125,CS1591,S1172"。构建后，警告消失了。 - Andrei Drynov

感谢回答问题而不是对是否抑制警告进行演讲！（原意翻译，无添加） - Dalbir Singh

在我看来，这是首选的选项，因为它允许关闭我们不想要的项目，比如单元测试，同时保留其他项目。 - Michael

Answer 3

你也可以修改项目的.csproj文件，在第一个<PropertyGroup>内包含一个<noWarn>1591</noWarn>标签。来自Alexandru Bucur的文章。

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

- DotNetPadawan

---

这应该是当今的答案。 - Edgar Froes

同意。大多数答案在其他编辑器（如Visual Studio Code）中不起作用。 - Krzysztof Czelusniak

Answer 4

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

重新编译即可消除警告。

- Chris

---

只要你不需要生成XML文档并且不介意XML注释无法得到验证，这种方法就是可行的。 - Keith

如果您想保留非自动生成的文件中的警告信息，则此方法不适用。为了消除一部分警告而删除所有警告似乎有些过头了。此外，在大多数公司，实际上会在所有不包含自动生成代码的文件中创建XML注释是一种常见做法。此外，用户要求解决方案不仅仅是简单地删除XML注释功能，因此这并不能回答问题。 - SubliemeSiem

这帮助我弄清楚为什么会收到有关禁用 XML 注释的警告，因此我可以通过勾选方框来修复它，基本上是相反于此回答的内容。 - computercarguy

Answer 5

Visual Studio 2022:

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

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

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

注意：在编辑器配置设计器中抑制SA0001对我不起作用。只能手动在文件中设置规则。

- Vladislav Horbachov

Answer 6

你可以使用.editorconfig文件来逐个文件地选择性地禁用它 - 例如，如果你有一个特定的源文件（或多个文件），你可以使用以下方式：

per-file。

# single file
[IgnoreThisFile.cs]
dotnet_diagnostic.CS1591.severity = none

# multiple files, matching on specific naming convention
[*{Type,Stuff,Things}.cs]
dotnet_diagnostic.CS1591.severity = none

请注意，我在持续管理此警告方面的经验是参差不齐的，但在当前版本（17.4.4+）的VS2022中，它似乎很稳定。确保.editorconfig在您的文件夹结构中处于足够“高”的级别，以便它适用于您所有的源文件（或者根据您的需要，在特定的文件夹级别使用多个文件）。

- Rory Solley

---

这是我一直在寻找的答案。我希望将解决方案中的所有内容都记录下来，但不包括出现在*.designer.cs文件中的类。这绝对是Visual Studio目前最好的解决方案。它并不像SuppressMessageAttribute那样脆弱或晦涩，并且不需要定义CODE_ANALYSIS符号，就像那个属性一样。 - dodexahedron

Answer 7

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

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

这真的没有自动完成的方法吗？每当自动生成的代码覆盖文件时，您都需要重新执行此操作。

- Kjellski

---

我认为这个警告不应该出现在自动生成的内容中，也许你需要检查项目属性中的相应设置。 - Gorgsenegger

不，只需启用XML注释警告即可显示所有内容。并且没有禁用自动生成代码的选项。因此，在需要重新生成代码时，请使用该片段。 - Kjellski

在项目属性的“代码分析”下，有一个选项“抑制生成代码的结果”。在每次代码重建后重新运行宏并不是一个真正的解决方案。如果上述选项对您无效，也许可以调整代码生成器以自动添加#pragma指令？ - Laoujin

@Laoujin，感谢您的评论，但正如我所提到的，我也不喜欢这个解决方案。我看不出有什么理由会被踩，我已经尝试了您提到的设置，但没有成功。您是否有机会尝试一下您的WebService导入解决方案呢？ - Kjellski

Answer 8

为修复此规则的违反，请将XML文档文件作为项目输出的一部分启用，方法是在项目文件中添加 true。

提及位置：

https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA0001.md#how-to-fix-violations

- Peeyush

---

这不是同样的警告信息。事实上，启用XML文档就是导致首次出现警告信息的原因。 - General Grievance