缺少公开可见类型或成员的 XML 注释答案

【问题标题】：Missing XML comment for publicly visible type or member缺少公开可见类型或成员的 XML 注释
【发布时间】：2010-09-17 06:15:09
【问题描述】：

我收到此警告：“缺少公开可见类型或成员的 XML 注释”。

如何解决？

【问题讨论】：

我在 Visual Studio 中也看到了这一点。有人知道这个警告来自什么软件吗？风格警察？外汇警察？代码分析？如何关闭它？

标签： c# 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，我不会设置它们，它们是更具体的错误，假设你设置了 ///
然后你在参数中犯了一个错误，你应该得到警告

【解决方案4】：

还有另一种方法可以抑制这些消息，而无需任何代码更改或编译指示块。使用 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("{0}{1}", LogFilePath, FileName);
}

显示警告缺少公开可见类型或成员“.EventLogger()”的 XML 注释

我为该成员添加了评论并且警告消失了。

///<Summary>
/// To write a log <Anycomment as per your code>
///</Summary>
public EventLogger()
{
    LogFile = string.Format("{0}{1}", 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()
{
}

【讨论】：