Missing XML comment for publicly visible type or member

Question

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

How to solve this?

Suctorial

I see this too in Visual Studio. Anyone know what software this warning comes from? Style Cop? Fx Cop? Code Analysis? How can I turn it off? – Nephogram

Answer 1

5 options:

• 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 1591 to disable the warning just for some bits of code (and #pragma warning restore 1591 afterwards)
• Ignore the warnings (bad idea - you'll miss new "real" warnings)

Chiastolite

@Jon, found the solution: If you get this warning for gereated code with a partial class, look for the "other half" of the partial class which is not generated. If you add a XML comment there, the warning for the generated code disappers. I had this warning for the App class in the App.g.i.cs file generated from the XAML code in a WP7 project. To resolve it, I had to add a XML comment in the App.xaml.cs file (which is not generated). – Kalli

@MarcelW: Ah, so it's not for the generated members? Or are they all internal anyway? That would make sense... – Chiastolite

Also, if you're getting this warning from a Service Reference Auto-generated code, you can right-click on the service reference, choose "Configure Service Reference...", then change "Access level for generated classes" to Internal. – Peptide

6. Auto-generate stub docs for existing methods. This way you will be able to track new undocumented code which can be easily dealt with case by case. – Sexpartite

In case you are disabling the warnings as @NickJ explaind, make sure you are changing it for all the configurations, and not only for debug \ release. – Measureless

One more option: set verbosity to minimal (or quiet). – Cranmer

In case you're looking to do the same for a VB.Net project, there is no GUI for that and you need to edit the .vbproj by hand. Insert a <NoWarn>1591</NoWarn> (or add to the existing value). – Ratable

You can also add this as a class attribute if you want to suppress code for an entire class: [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Usage", "CS1591")] – Gail

I also had to add 1573. However, at least when using ReSharper, you can easily get the code to be disabled from the warning "CS...." in the source code. – Disobey

If you're building via the msbuild commandline then you may need to add /p:NoWarn=1591 to the cmdline args. – Brickkiln

Alternative sixth option: Remove public from the outermost containing type (such as class). When you remove the outermost public modifier, the members are no longer publicly visible, hence XML documentation is optional. Will it not build? You may need to remove a couple of other public modifiers to maintain consistent accessibility. Is the type used by other assemblies? Then you must keep public of course. In that case, supply the documentation; it will help those outside consumers of your type. – Acrylyl

The only solution that worked for me is @cloudstrifebro's one. (Lee Grissom's input is great, but as we have internals also declared as must-document, it does not work for me). VS2019 added a new scope, one can suppress them now by namespace, including sub-namespaces: [assembly: SuppressMessage("Microsoft.Usage", "CS1591", Justification = "Generated code.", Scope = "namespaceanddescendants", Target = "~N:<Your.Name.Space>")] – Guerdon

Where is the "Generate XML comment for me" option!? I can't find it in any of the auto-correct context menus. Surely, it should be there, no? – Vicious

@Balage: I normally find that typing /// in above a member generates all the relevant tags for me. – Chiastolite

Looks like NoWarn is semicolon-separated instead of comma-separated in C# csproj files. – Campbellbannerman

@Pang: Not in my experience. It may be that it can be semicolon-separated as well, but it can definitely be comma-separated. – Chiastolite

Answer 2

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

///<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.

The reason you 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.

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

Rodeo

+1 for mentioning GhostDoc. Never knew about that, it certainly makes documenting easier. – Evocation

+1 for giving the reason for the warning. Found the setting under Build in the project properties (VS 2008) and switched it off on the one project out of ten that mysteriously had it checked for no good reason. – Montero

Yes, this is the answer, thank you. Got this warning for a VS add-in for which I had removed the comments. – Lazes

-1 For recommending GhostDoc - the stupidest AddOn I've ever seen. It generates documentation. Now pause a second to think about it. You want your code to be more understandable so you use a tool that generates documentation solely based on the method name and arguments types. Does it make sense to you? The user can see the name and types of the arguments, add comment to DateTime date- The date really doesn't help. – Veron

@gdoron, it might not have occurred to you, but you can edit the documentation GhostDoc generates, which will save you a lot of time vs. writing the entire documentation from scratch. – Polynices

Writing the /// generates empty template, this all you need and helpful. GhostDoc is stupid and contra-productive . #Not-convinced. – Veron

GhostDoc does more than just guesses what the comments should be -- though most of the time, it's pretty close and you just need to edit a few words instead of typing the whole thing out -- and if you're documenting correctly (and you probably aren't), there's a template for most things, how they need to be worded (for properties, constructors, etc.), and GhostDoc puts those in -- even cooler: If you're in a child class, it can fill in the documentation with that from the base class as a template to work with, instead of copying it by hand -- it puts in the exception blurbs, etc. – Frenchy

Some of the GhostDoc template can be useful (public methods of public APIs), but if it can guess the wording from the name, it is because the name is clear enough (Clean Code). Also, if a child class needs comments that the parent already has, something is going wrong there (DRY and don't let the tool to break DRY). – Faubourg

What ghostdoc gives me is a reminder to name the method better if the generated stuff looks dumb. plus it tacks on all the intellisense additives. i like it. i understand that it's duplicating "self-documenting code" if you name things well but you get lots of little extras like references to exceptions the method throws and even lets you fill in info about the return type if needed. you'd have to bang all that out yourself if you wanted it there. then it generates a (sometimes) help CHM for you too. Lots to like about it. you can even create your own templates for reasons. – Thrive

Answer 3

There is another way you can suppress these messages without the need for any code change or pragma blocks. Using Visual Studio - Go to project properties > Build > Errors and Warnings > Suppress Warnings - append 1591 to list of warning codes.

Jolynnjon

This is by far, the best, easiest, and fastest to implement answer I've seen thus far for this issue. It is a repeat of another answer above, but this one is much more visually descriptive giving a quick instant answer. Thank you very much. – Alehouse

Best answer here. Prevents me from scattering my codebase with #pragma warning disable everywhere, which is just annoying. – Karolynkaron

Answer 4

Suppress Warnings for XML comments

(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/

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

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

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

You can suppress every warning in 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

Lemuellemuela

I only needed to add 1591 to suppress the Xml comment warnings. – Wentworth

Thanks for the code list! I've started to gather them one by one and on the 3rd build with warnings I came to idea that I need to take it from somewhere as is :) – Gates

Something is not right, 1591 also removes "Obsolete" warnings, but MS indicates it's about comments only msdn.microsoft.com/en-us/library/zk18c1w9.aspx – Connivent

I also checked on MS all 1572,1571,1573,1587,1570, and I would not set them, they are more specific errors, let say you have set ///<summary> and then you make a mistake in params, you should get warning – Connivent

Answer 5

Insert an XML comment. ;-)

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

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

Geber

I always comment methods, but for properties (which are tehnically methods but typically have trivial implementations and self-evident names) I prefer to avoid the tedium and repetition of adding superfluous XML comments. – Afterward

Answer 6

A really simple way to suppress the warning is to add a property in the .csproj file:

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

Indiscrimination

This should be the top answer, others make assumptions of tools in use – Refract

Answer 7

This is because an XML documentation file has been specified in your Project Properties and Your Method/Class is public and lack documentation.
You can either :

1. Disable XML documentation:

   Right Click on your Project -> Properties -> 'Build' tab -> uncheck XML Documentation File.

2. Sit and write the documentation yourself!

Summary of XML documentation goes like this:

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

Selfinsurance

Answer 8

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

Yvor

Answer 9

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.

Additionally I wanted to point out that the warning only expresses on publicly visible members. So, if you setup your class library to only expose what it needs to, you can get by without documenting private and internal members.

Erigena

Answer 10

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 1591 you can also restore the warning : #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 warning disable 1591 and in case you need to restore it, use: #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; }
    }
}

Note that pragma directive start at the begin of line

Outofdate

Answer 11

Jon Skeet's answer works great for when you're building with VisualStudio. However, if you're building the sln via the command line (in my case it was via Ant) then you may find that msbuild ignores the sln supression requests.

Adding this to the msbuild command line solved the problem for me:

/p:NoWarn=1591

Brickkiln

Answer 12

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 Documentation checkbox.

Rebuild and no warnings.

Cumae

Be sure to also check all of your build configurations. I had unchecked it for Debug but not for Release and was very confused. – Huzzah

This solution is not a solution in case of WebAPI documentation. You need this option on, but suppress the warnings. – Connivent

Answer 13

#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

Catch

Answer 14

Setting the warning level to 2 suppresses this messages. Don't know if it's the best solution as it also suppresses useful warnings.

Bennie

Rather than opting for this, i guess, disabling the xml documentation reduces risks. – Selfinsurance

Answer 15

You need to add /// Comment for the member for which warning is displayed.

see below code

public EventLogger()
{
    LogFile = string.Format("{0}{1}", LogFilePath, FileName);
}

It displays warning Missing XML comment for publicly visible type or member '.EventLogger()'

I added comment for the member and warning gone.

///<Summary>
/// To write a log <Anycomment as per your code>
///</Summary>
public EventLogger()
{
    LogFile = string.Format("{0}{1}", LogFilePath, FileName);
}

Jolo

Answer 16

The answer from @JonSkeet is almost complete. If you want to disable it for every project in your solution you could add the row below to a .editorconfig file.

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

See file hierarchy and precedence on where to add the file:

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

Affair

Answer 17

Late in here but many solutions in this thread focus on removing the warnings entirely within the project or within the class.

If you want to keep the legitimate warnings but remove some - e.g. the cancellationToken on a WebApi controller when you expose the API using swagger (the api user does not need this - it is supplied by DI).

Ugly and obvious but at least in this case cancellation tokens are the last param.

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

Brayton

Answer 18

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()
{
}

Glucinum