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

Question

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

如何解决这个问题？

Answer 1

5个选项：

• 填写文档注释（很好，但很耗时）
• 关闭评论生成（在项目属性中）
• 禁用项目属性中的警告（在“项目属性”中转到项目属性-> 构建>“错误和警告”（部分），抑制警告（文本框），添加 1591（逗号分隔列表））。 默认情况下它会更改活动配置，考虑将配置更改为全部。
• 使用#pragma warning disable 1591仅针对某些代码位禁用警告（然后使用#pragma warning restore 1591 ）
• 忽略警告（坏主意 - 你会错过新的“真实”警告）

Answer 2

当然，将 XML 注释添加到公开可见的类型和成员 :)

///<Summary>
/// Gets the answer
///</Summary>
public int MyMethod()
{
   return 42;
}

您需要对所有成员进行这些<summary>类型的评论 - 这些也会显示在智能感知弹出菜单中。

您收到此警告的原因是您已将项目设置为输出文档 xml 文件（在项目设置中）。 这对于类库（.dll 程序集）很有用，这意味着您的 .dll 用户可以在 Visual Studio 中获取您的 API 的智能感知文档。

我建议您为自己获取一份GhostDoc Visual Studio 插件的副本。使记录变得更加容易。

Answer 3

禁止 XML 注释的警告

（不是我的工作，但我发现它很有用，所以我已经包含了文章和链接）

http://bernhardelbl.wordpress.com/2009/02/23/suppress-warnings-for-xml-comments/

在这里，我将向您展示如何在 Visual Studio 构建后抑制 XML 注释的警告。

背景

如果您在 Visual Studio 项目设置中选中了“XML 文档文件”标记，则会创建一个包含所有 XML 注释的 XML 文件。 此外，由于缺少或错误的 XML 注释，您还会在设计器生成的文件中收到很多警告。 虽然有时警告可以帮助我们改进和稳定我们的代码，但收到数百条 XML 注释警告只是一种痛苦。

警告

缺少公开可见类型或成员的 XML 注释……
对 ... 的 XML 注释有一个用于“...”的参数标记，但没有该名称的参数 参数“...”在“...”的 XML 注释中没有匹配的参数标记（但其他参数有）

解决方案

您可以禁止 Visual Studio 中的每个警告。

• 右键单击 Visual Studio 项目/属性/生成选项卡

• 在“抑制警告”中插入以下警告编号：1591,1572,1571,1573,1587,1570

Answer 4

还有另一种方法可以抑制这些消息，而无需任何代码更改或编译指示块。 使用 Visual Studio - 转到项目属性 > 构建 > 错误和警告 > 抑制警告 - 将 1591 附加到警告代码列表。

Answer 5

插入 XML 注释。 ;-)

/// <summary>
/// Describe your member here.
/// </summary>
public string Something
{
    get;
    set;
}

乍一看，这可能看起来像是一个笑话，但实际上它可能很有用。 对我来说，即使是私有方法，考虑什么方法也是有帮助的（当然，除非真的很微不足道）。

Answer 6

这是因为在您的项目属性中指定了 XML 文档文件，并且您的方法/类是公开的并且缺少文档。
您可以：

1. 禁用 XML 文档：

   右键单击您的项目 -> 属性 -> '构建' 选项卡 -> 取消选中 XML 文档文件。

2. 坐下来自己写文档！

XML 文档的摘要如下所示：

/// <summary>
/// Description of the class/method/variable
/// </summary>
..declaration goes here..

Answer 7

抑制警告的一种非常简单的方法是在.csproj文件中添加一个属性：

<Project>
    <PropertyGroup>
        ...     
        <!--disable missing comment warning-->
        <NoWarn>$(NoWarn);1591</NoWarn>
    </PropertyGroup>
...

Answer 8

我知道这是一个非常古老的线程，但这是谷歌上的第一个响应，所以我想我会添加以下信息：

此行为仅在“项目属性”->“构建”下的警告级别设置为 4 时发生。 除非您真的需要那么多信息，否则您可以将其设置为 3，您将摆脱这些警告。 当然，更改警告级别不仅仅影响评论，因此如果您不确定会丢失什么，请参阅文档：
https://msdn.microsoft.com/en-us/library/thxezb7y.aspx

Answer 9

我想在此处列出的答案中添加一些内容：

正如 Isak 所指出的，XML 文档对类库很有用，因为它为 Visual Studio 中的任何使用者提供智能感知。 因此，一个简单而正确的解决方案是简单地关闭任何顶级项目（如 UI 等）的文档，这不会在其自己的项目之外实现。

此外，我想指出，该警告仅针对公开可见的成员。 因此，如果您将类库设置为仅公开它需要的内容，则无需记录private成员和internal成员即可。

Answer 10

在您的解决方案中，一旦您选中生成 XML 文档文件的选项，它就会开始检查您的公共成员是否拥有 XMLDoc，如果没有，您将收到每个元素的警告。 如果您真的不想发布您的 DLL，并且您不需要文档，请转到您的解决方案，构建部分并将其关闭，否则如果您需要它，请填写它们，如果有不重要的属性和字段，只需使用预编译器指令超越它们#pragma warning disable 1591你也可以恢复警告： #pragma warning restore 1591

杂注用法：代码中的任何位置在您收到编译器警告的位置之前...（对于文件，将其放在标头中，并且您不需要再次启用它，对于单个类环绕类，或对于方法环绕一个方法，或者......你不需要包装它，你可以调用它并随便恢复它（从文件开头开始，在方法内结束）），编写以下代码：

#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 指令从行首开始

Answer 11

文件>编辑>查看项目（单击）

下拉弓的底部（单击Open/Current work > Properties ），在“Output”下的“Build”处打开项目属性页面。 “取消选中” XML 文档复选框。

重建并且没有警告。

Answer 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

Answer 13

将警告级别设置为 2 会禁止显示此消息。 不知道这是否是最好的解决方案，因为它还会抑制有用的警告。

Answer 14

当您使用 VisualStudio 进行构建时，Jon Skeet 的回答非常有用。 但是，如果您通过命令行构建 sln（在我的情况下是通过 Ant），那么您可能会发现 msbuild 忽略了 sln 抑制请求。

将此添加到 msbuild 命令行为我解决了这个问题：

/p:NoWarn=1591

Answer 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);
}

Answer 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
    {

Answer 17

@JonSkeet 的答案几乎是完整的。 如果您想为解决方案中的每个项目禁用它，您可以将下面的行添加到.editorconfig文件中。

dotnet_diagnostic.CS1591.severity = none

https://github.com/dotnet/roslyn/issues/41171#issuecomment-577811906

https://docs.microsoft.com/en-us/visualstudio/ide/create-portable-custom-editor-options?view=vs-2022

查看文件层次结构和添加文件的优先级：

https://docs.microsoft.com/en-us/visualstudio/ide/create-portable-custom-editor-options?view=vs-2019#file-hierarchy-and-precedence

Answer 18

将属性附加到方法后，我收到了该消息

[webMethod]
public void DoSomething()
{
}

但正确的方法是这样的：

[webMethod()] // Note the Parentheses 
public void DoSomething()
{
}