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

我得到这个警告:“缺少公开可见类型或成员的XML注释”。

如何解决这个问题?

234144 次浏览
小开

插入一个XML注释。: -)

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

乍一看这可能像一个笑话，但它是有用的。对我来说，思考方法对于私有方法的作用是有帮助的(当然，除非非常琐碎)。

小开

5个选项:

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

当然要向公开可见的类型和成员添加XML注释:)

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

所有成员上都需要这些<summary>类型的注释——这些注释也会显示在智能感知弹出菜单中。

原因你得到这个警告是因为你已经将你的项目设置为输出文档xml文件(在项目设置中)。这对于类库(.dll程序集)很有用，这意味着.dll的用户可以在visual studio中获得API的智能感知文档。

我建议你给自己准备一个GhostDoc Visual Studio AddIn..使记录变得更容易。

小开

禁止XML注释的警告

(不是我的作品，但我发现它很有用，所以我把文章&链接)

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

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

背景

如果您已经选中了“XML文档文件”;标记后，一个包含所有XML注释的XML文件就被创建了。此外，由于缺少或错误的XML注释，您还将在设计器生成的文件中得到大量警告。虽然有时警告可以帮助我们改进和稳定代码，但收到数百个XML注释警告只是一种痛苦。

警告

< p > 缺少公开可见类型或成员的XML注释…
关于…的XML注释有一个用于'…'的参数标记，但没有该名称的参数 参数'…'在'…'的XML注释中没有匹配的参数标签(但其他参数有)

解决方案

你可以在Visual Studio中压制每一个警告。

  • 右键单击Visual Studio项目/属性/构建选项卡

  • 在“抑制警告”中插入以下警告数字:1591,1572,1571,1573,1587,1570

小开

我想对这里列出的答案补充一些东西:

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

另外，我想指出的是，警告只对公开可见的成员表示。因此，如果你将类库设置为只公开它需要公开的内容，你就可以不记录private和internal成员。

小开

在将一个属性附加到一个方法后，我得到了这条消息

[webMethod]
public void DoSomething()
{
}

但正确的做法是:

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

文件 > 编辑 > 查看项目(点击)

下拉弓的底部(点击打开/当前的工作 > 属性)， 打开项目属性页在“构建”下的“输出”。

. "Uncheck" XML文档复选框

重建，没有警告。

小开
在您的解决方案中，一旦选中生成XML Document文件的选项，它就会开始检查您的公共成员是否拥有XMLDoc，如果没有，您将收到每个元素的警告。 如果你真的不想释放你的DLL，而且你也不需要文档，那就去你的解决方案，构建部分，并关闭它，否则如果你需要它，那么就填满它们，如果有不重要的属性和字段，就用预编译器指令来超越它们 #pragma warning disable 1591 您也可以恢复警告: #pragma warning restore 1591 < / p >

Pragma用法:在代码中任何你得到编译器警告的地方之前…(对于文件，把它放在头文件中，你不需要再次启用它，对于单个类环绕一个类，或方法环绕一个方法，或…你也不需要把它包装起来，你可以随意地调用它并恢复它(在文件的开始处开始，并在方法中结束))，编写以下代码:

< p > #pragma warning disable 1591 如果你需要恢复它，使用: #pragma warning restore 1591 < / p >

这里有一个例子:

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指令开始在行开始

小开
我知道这是一个非常旧的线程，但它是谷歌上的第一个响应，所以我想我应该添加这一点信息:

这种行为只发生在“项目属性”->“构建”下的警告级别设置为4时。除非你真的需要那么多的信息，你可以把它设置为3，你就可以摆脱这些警告。当然，更改警告级别影响的不仅仅是注释，所以如果您不确定会遗漏什么，请参考文档:
https://msdn.microsoft.com/en-us/library/thxezb7y.aspx < / p >
小开 
#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
小开

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

小开

这是因为您的项目属性中指定了一个XML文档文件，而您的方法/类是公共的，缺乏文档 你可以:

    关闭XML文档:

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

    李< /引用> < / >
  1. 坐下来自己写文档吧!

XML文档的总结如下:

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

您需要为显示警告的成员添加/// Comment。

参见下面的代码

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);
}
小开

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

enter image description here

小开

Jon Skeet的回答非常适用于使用VisualStudio进行构建。但是，如果您通过命令行构建sln(在我的例子中是通过Ant)，那么您可能会发现msbuild忽略sln抑制请求。

添加到msbuild命令行解决了我的问题:

/p:NoWarn=1591
小开

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

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

在这里的后面，但是这个线程中的许多解决方案都专注于在项目或类中完全删除警告。

如果你想保留合法的警告，但删除一些-例如，当你使用swagger公开API时，WebApi控制器上的cancellationToken (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
{
小开

来自@JonSkeet的答案几乎完成了。如果你想在解决方案中的每个项目中禁用它，你可以将下面的行添加到.editorconfig文件中。

dotnet_diagnostic.CS1591.severity = none

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

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

查看文件层次结构和优先级添加文件的位置:

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


提交答案