缺少公开可见类型或成员的 XML 注释
Posted
技术标签:
【中文标题】缺少公开可见类型或成员的 XML 注释【英文标题】：Missing XML comment for publicly visible type or member 【发布时间】：2010-09-17 06:15:09 【问题描述】：我收到此警告：“”。
如何解决？
【问题讨论】：
我在 Visual Studio 中也看到了这一点。有人知道这个警告来自什么软件吗？风格警察？外汇警察？代码分析？如何关闭它？ 【参考方案1】：5 个选项：
填写文档 cmets（很好，但很耗时） 关闭评论生成（在项目属性中） 禁用项目属性中的警告（在“项目属性”中转到项目属性 -> 构建 >“错误和警告”（部分），抑制警告（文本框），添加 1591（逗号分隔列表））。默认情况下会更改 Active Configuration，请考虑将配置更改为 All。 使用#pragma warning disable 1591 仅针对某些代码位禁用警告（之后使用#pragma warning restore 1591）
忽略警告（坏主意 - 您会错过新的“真实”警告）
【讨论】：
@Jon，找到了解决方案：如果您收到带有部分类的生成代码的警告，请查找未生成的部分类的“另一半”。如果您在此处添加 XML 注释，生成代码的警告就会消失。我从 WP7 项目中的 XAML 代码生成的 App.g.i.cs 文件中的 App 类有此警告。为了解决这个问题，我不得不在 App.xaml.cs 文件中添加一个 XML 注释（未生成）。 @MarcelW：啊，所以不是生成的成员？还是它们都是内部的？这是有道理的...... 另外，如果您从 服务参考 自动生成的代码中收到此警告，您可以右键单击服务参考，选择“配置服务参考.. .”，然后将“生成的类的访问级别”更改为内部。 如果您按照@NickJ 的说明禁用警告，请确保为所有配置更改它，而不仅仅是调试\发布。 如果您想禁止整个类的代码，也可以将其添加为类属性：[System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Usage", "CS1591")]跨度> 【参考方案2】：当然，将 XML cmets 添加到公开可见的类型和成员中：)
///<Summary>
/// Gets the answer
///</Summary>
public int MyMethod()
return 42;
所有成员都需要这些 <summary> 类型 cmets - 这些也会显示在智能感知弹出菜单中。
您收到此警告的原因是因为您已将项目设置为输出文档 xml 文件（在项目设置中）。这对于类库（.dll 程序集）很有用，这意味着您的 .dll 用户可以在 Visual Studio 中获取您的 API 的智能感知文档。
我建议您为自己获取一份 GhostDoc Visual Studio 插件的副本。使记录变得更加容易。
【讨论】：
+1 用于提及 GhostDoc。从来不知道，它确实使记录更容易。 +1 用于给出警告的原因。在项目属性 (VS 2008) 中的 Build 下找到设置，然后在十个项目中的一个项目中关闭它，该项目神秘地无缘无故地检查了它。 -1 推荐GhostDoc - 我见过的最愚蠢的插件。它生成文档。现在停下来想一想。您希望您的代码更易于理解，因此您可以使用仅基于方法名称和参数类型生成文档的工具。这对你有意义吗？用户可以看到参数的名称和类型，添加注释到DateTime date- 日期真的没有帮助。
@gdoron，您可能没有想到，但您可以编辑 GhostDoc 生成的文档，与从头开始编写整个文档相比，这将为您节省大量时间。
GhostDoc 不仅仅是猜测 cmets 应该是什么——尽管大多数时候，它非常接近，你只需要编辑几个单词而不是输入整个内容——如果你的文档记录正确（你可能没有），大多数事情都有一个模板，它们需要如何措辞（用于属性、构造函数等），GhostDoc 把它们放进去——甚至更酷：如果你在子类中，它可以使用基类中的文档作为模板来填充文档，而不是手动复制它——它会放入异常简介等。【参考方案3】：
抑制 XML cmets 的警告
（不是我的作品，但我发现它很有用，所以我已经包含了文章和链接）
http://bernhardelbl.wordpress.com/2009/02/23/suppress-warnings-for-xml-comments/
在这里，我将向您展示如何在 Visual Studio 构建后抑制 XML cmets 的警告。
背景
如果您在 Visual Studio 项目设置中选中了“XML 文档文件”标记，则会创建一个包含所有 XML cmets 的 XML 文件。此外，由于 XML cmets 丢失或错误，您还会在设计器生成的文件中收到很多警告。虽然有时警告可以帮助我们改进和稳定我们的代码，但收到数百条 XML 注释警告只是一种痛苦。
警告
缺少公开可见类型或成员的 XML 注释…… 对 ... 的 XML 注释有一个用于“...”的参数标记，但没有该名称的参数 参数“...”在“...”的 XML 注释中没有匹配的参数标记（但其他参数有）
解决方案
您可以在 Visual Studio 中隐藏所有警告。
右键单击 Visual Studio 项目/属性/构建选项卡
在“抑制警告”中插入以下警告编号：1591,1572,1571,1573,1587,1570
【讨论】：
我只需要添加 1591 即可抑制 Xml 注释警告。 感谢代码列表！我已经开始一个一个地收集它们，在第三个版本的警告中我开始想到我需要从某个地方拿走它 :) 有些不对劲，1591 还删除了“过时”警告，但 MS 表示它仅与 cmets 有关 msdn.microsoft.com/en-us/library/zk18c1w9.aspx 我还在 MS 上检查了所有 1572,1571,1573,1587,1570，我不会设置它们，它们是更具体的错误，假设你设置了 ///还有另一种方法可以抑制这些消息，而无需任何代码更改或编译指示块。使用 Visual Studio - 转到项目属性 > 构建 > 错误和警告 > 抑制警告 - 将 1591 附加到警告代码列表。
【讨论】：
这是迄今为止我所见过的关于此问题的最佳、最简单和最快的实施答案。这是上面另一个答案的重复，但这个答案在视觉上更具描述性，给出了一个快速的即时答案。非常感谢。 最佳答案在这里。阻止我将我的代码库与#pragma warning disable 分散到任何地方，这很烦人。【参考方案5】：
插入 XML 注释。 ;-)
/// <summary>
/// Describe your member here.
/// </summary>
public string Something
get;
set;
乍一看这可能看起来像个笑话，但它实际上可能很有用。对我来说，考虑一下方法对私有方法的作用是有帮助的（当然，除非真的很微不足道）。
【讨论】：
我总是评论方法，但是对于 properties（这些是技术上的方法，但通常具有琐碎的实现和不言而喻的名称），我更愿意避免添加多余的乏味和重复XML cmets。【参考方案6】：这是因为在您的项目属性中指定了一个 XML 文档文件，并且您的方法/类是公开的并且缺少文档。 您可以：
-
禁用 XML 文档：
坐下来自己编写文档！右键单击您的项目 -> 属性 -> '构建' 选项卡 -> 取消选中 XML 文档文件。
XML 文档摘要如下：
/// <summary>
/// Description of the class/method/variable
/// </summary>
..declaration goes here..
【讨论】：
谢谢。我认为这种方式是禁用警告的最佳正确方式【参考方案7】：抑制警告的一个非常简单的方法是在.csproj 文件中添加一个属性：
<Project>
<PropertyGroup>
...
<!--disable missing comment warning-->
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
...
【讨论】：
我喜欢这些简单的解决方案！【参考方案8】：我知道这是一个非常老的帖子，但这是谷歌上的第一个回复，所以我想我会添加以下信息： 此行为仅在“项目属性”->“构建”下的警告级别设置为 4 时发生。除非您真的需要那么多信息，否则您可以将其设置为 3，您将摆脱这些警告。当然，更改警告级别不仅仅影响 cmets，因此如果您不确定自己会丢失什么，请参阅文档：https://msdn.microsoft.com/en-us/library/thxezb7y.aspx
【讨论】：
【参考方案9】：我想在此处列出的答案中添加一些内容：
正如 Isak 所指出的，XML 文档对类库很有用，因为它为 Visual Studio 中的任何使用者提供智能感知。因此，一个简单而正确的解决方案是简单地关闭任何***项目（如 UI 等）的文档，这不会在其自己的项目之外实现。
此外，我想指出，该警告仅针对公开可见成员。因此，如果您将类库设置为仅公开它需要的内容，则无需记录 private 和 internal 成员即可。
【讨论】：
【参考方案10】：在您的解决方案中，一旦您选中生成 XML 文档文件的选项，它就会开始检查您的公共成员是否拥有 XMLDoc，如果没有，您将收到每个元素的警告。
如果您真的不想发布您的 DLL，并且您也不需要文档，请转到您的解决方案，构建部分并将其关闭，否则如果您需要它，请填写它们，如果有不重要的属性和字段，只需用预编译器指令超越它们
#pragma warning disable 1591
您还可以恢复警告：
#pragma warning restore 1591
pragma 用法：代码中的任何位置，在您收到编译器警告的位置之前...方法包裹一个方法，或者......你不需要包裹它，你可以调用它并随便恢复它（从文件开头开始，并在方法内结束），编写以下代码：
#pragma warning disable 1591
如果您需要恢复它，请使用：
#pragma warning restore 1591
这里是一个例子：
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
using RealEstate.Entity.Models.Base;
namespace RealEstate.Models.Base
public class CityVM
#pragma warning disable 1591
[Required]
public string Id get; set;
[Required]
public string Name get; set;
public List<LanguageBasedName> LanguageBasedNames get; set;
[Required]
public string CountryId get; set;
#pragma warning restore 1591
/// <summary>
/// Some countries do not have neither a State, nor a Province
/// </summary>
public string StateOrProvinceId get; set;
注意 pragma 指令从行首开始
【讨论】：
【参考方案11】：文件 > 编辑 > 查看项目（点击）
下拉弓的底部（点击Open/Current work > Properties）， 在“输出”下的“构建”处打开项目属性页面。 “取消选中”XML 文档复选框。
重建并且没有警告。
【讨论】：
一定要检查所有的构建配置。我取消了 Debug 的勾选，但没有勾选 Release，我很困惑。 此解决方案不是 WebAPI 文档的解决方案。您需要启用此选项，但禁止显示警告。【参考方案12】：#pragma warning disable 1591
#pragma warning disable 1591
#pragma warning disable 1572
#pragma warning disable 1571
#pragma warning disable 1573
#pragma warning disable 1587
#pragma warning disable 1570
【讨论】：
【参考方案13】：将警告级别设置为 2 会禁止显示此消息。不知道这是否是最好的解决方案，因为它还会抑制有用的警告。
【讨论】：
我猜，与其选择这个，不如禁用 xml 文档可以降低风险。【参考方案14】：Jon Skeet 的回答非常适合您使用 VisualStudio 进行构建。但是，如果您通过命令行（在我的情况下是通过 Ant）构建 sln，那么您可能会发现 msbuild 忽略了 sln 抑制请求。
将此添加到 msbuild 命令行为我解决了这个问题：
/p:NoWarn=1591
【讨论】：
【参考方案15】：您需要为显示警告的成员添加 /// 注释。
见下面代码
public EventLogger()
LogFile = string.Format("01", LogFilePath, FileName);
显示警告 缺少公开可见类型或成员“.EventLogger()”的 XML 注释
我为该成员添加了评论并且警告消失了。
///<Summary>
/// To write a log <Anycomment as per your code>
///</Summary>
public EventLogger()
LogFile = string.Format("01", LogFilePath, FileName);
【讨论】：
【参考方案16】：这里很晚，但该线程中的许多解决方案都侧重于完全在项目或类中删除警告。
如果您想保留合法警告但删除一些警告 - 例如当您使用 swagger 公开 API 时，WebApi 控制器上的 cancelToken（api 用户不需要这个 - 它由 DI 提供）。
丑陋而明显，但至少在这种情况下，取消标记是最后一个参数。
/// <summary>
/// Creates a Service
/// </summary>
/// <param name="service">The Service Definition</param> (**note no cancellation token param**)
/// <returns>A newly created item</returns>
/// <response code="201">Returns the newly created service</response>
/// <response code="400">If there are validation errors with the submitted json body</response>
/// <response code="409">Conflict. The service already exists</response>
/// <response code="500">Because life is never perfect</response>
[ProducesResponseType(typeof(Service), 201)]
[ProducesResponseType(400)]
[ProducesResponseType(409)]
[ProducesResponseType(500)]
[HttpPost]
public async Task<ActionResult> ServiceCreate([FromBody] ServicePostRequest service,
#pragma warning disable 1573
CancellationToken cancellationToken = default) //**note: no warning**
#pragma warning restore 1573
【讨论】：
【参考方案17】：我在将属性附加到方法后收到该消息
[webMethod]
public void DoSomething()
但正确的做法是这样的：
[webMethod()] // Note the Parentheses
public void DoSomething()
【讨论】：
以上是关于缺少公开可见类型或成员的 XML 注释的主要内容，如果未能解决你的问题，请参考以下文章
类型“JavaCompile”属性“options.compilerArgumentProviders.apt$0.name”缺少输入或输出注释。升级到 Gradle 7 后出错