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

Missing XML comment for publicly visible type or member

提问by

I am getting this warning: "Missing XML comment for publicly visible type or member".

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

How to solve this?

如何解决这个问题？

回答by Matthias Meid

Insert an XML comment. ;-)

插入 XML 注释。;-)

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

This may appear like a joke at the first glance, but it may actuallybe useful. For me it turned out to be helpful to think about what methods do even for private methods (unless really trivial, of course).

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

回答by Jon Skeet

5 options:

5个选项：

• Fill in the documentation comments (great, but time-consuming)
• Turn off the comment generation (in project properties)
• Disable the warning in project properties (in 'Project properties' go to Project properties -> Build > "Errors and warnings" (section), Suppress Warnings (textbox), add 1591 (comma separated list)). By default it will change Active Configuration, consider to change configuration to All.
• Use #pragma warning disable 1591to disable the warning just for some bits of code (and #pragma warning restore 1591afterwards)
• Ignore the warnings (bad idea - you'll miss new "real" warnings)

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

回答by Isak Savo

Add XML comments to the publicly visible types and members of course :)

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

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

You need these <summary>type comments on all members - these also show up in the intellisense popup menu.

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

The reasonyou get this warning is because you've set your project to output documentation xml file (in the project settings). This is useful for class libraries (.dll assemblies) which means users of your .dll are getting intellisense documentation for your API right there in visual studio.

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

I recommend you get yourself a copy of the GhostDocVisual Studio AddIn.. Makes documenting much easier.

我建议您为自己准备一份GhostDocVisual Studio AddIn.. 使文档更容易。

回答by Sprotty

Suppress Warnings for XML comments

抑制 XML 注释的警告

(not my work, but I found it useful so I've included the article & link)

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

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

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

Here i will show you, how you can suppress warnings for XML comments after a Visual Studio build.

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

Background

背景

If you have checked the "XML documentation file" mark in the Visual Studio project settings, a XML file containing all XML comments is created. Additionally you will get a lot of warnings also in designer generated files, because of the missing or wrong XML comments. While sometimes warnings helps us to improve and stabilize our code, getting hundreds of XML comment warnings is just a pain. Warnings

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

Missing XML comment for publicly visible type or member …XML comment on … has a param tag for ‘…', but there is no parameter by that name Parameter ‘…' has no matching param tag in the XML comment for ‘…' (but other parameters do) Solution

缺少公开可见类型或成员的XML 注释……关于……的XML 注释具有“……”的 param 标记，但没有该名称的参数参数“……”在“……”的 XML 注释中没有匹配的 param 标记（但是其他参数做) 解决方案

You can suppress every warning in Visual Studio.

您可以取消 Visual Studio 中的每个警告。

• Right-click the Visual Studio project / Properties / Build Tab

• Insert the following warning numbers in the "Suppress warnings": 1591,1572,1571,1573,1587,1570

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

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

回答by Mike Guthrie

I wanted to add something to the answers listed here:

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

As Isak pointed out, the XML documentation is useful for Class Libraries, as it provides intellisense to any consumer within Visual Studio. Therefore, an easy and correct solution is to simply turn off documentation for any top-level project (such as UI, etc), which is not going to be implemented outside of its own project.

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

Additionally I wanted to point out that the warning only expresses on publicly visiblemembers. So, if you setup your class library to only expose what it needs to, you can get by without documenting privateand internalmembers.

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

回答by Coyolero

I got that message after attached an attribute to a method

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

[webMethod]
public void DoSomething()
{
}

But the correct way was this:

但正确的方法是这样的：

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

回答by tom

File> Edit> View Project(click)

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

Bottom of the drop down bow (click on Open/Current work> Properties), opened project properties page at "Build" under "Output". "Uncheck" XML Documentationcheckbox.

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

Rebuild and no warnings.

重建，没有警告。

回答by deadManN

In your solution, once you check the option to generate XML Document file, it start checking your public members, for having the XMLDoc, if they don't, you'll receive a warning per each element. if you don't really want to release your DLL, and also you don't need documentations then, go to your solution, build section, and turn it off, else if you need it, so fill them, and if there are unimportant properties and fields, just surpass them with pre-compiler instruction #pragma warning disable 1591you can also restore the warning : #pragma warning restore 1591

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

pragma usage: any where in code before the place you get compiler warning for... (for file, put it in header, and you do not need to enable it again, for single class wrap around a class, or for method wrap around a method, or ... you do not either need to wrap it around, you can call it and restore it casually (start in begin of file, and end inside a method)), write this code:

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

#pragma warning disable 1591and in case you need to restore it, use: #pragma warning restore 1591

#pragma warning disable 1591如果您需要恢复它，请使用： #pragma warning restore 1591

Here an example:

这里有一个例子：

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

Notethat pragma directive start at the begin of line

请注意pragma 指令从行首开始

回答by Marius Agur

I know this is a really old thread, but it's the first response on google so I thought I'd add this bit of information:

This behavior only occurs when the warning level is set to 4 under "Project Properties" -> "Build". Unless you really need that much information you can set it to 3 and you'll get rid of these warnings. Of course, changing the warning level affects more than just comments, so please refer to the documentation if you're unsure what you'll be missing:
https://msdn.microsoft.com/en-us/library/thxezb7y.aspx

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

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

回答by Petar

#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