Visual Studio Disabling Missing XML Comment Warning

Question

I have a project with over 500 Missing XML Comment warnings. I know I can remove the XML Comment feature, or paste empty comment snippets everywhere, but I'd prefer a generic solution where I can make one change that disables all warnings of this type.

What I do just now is putting

///<Summary>
/// 
///</Summary>

or

#pragma warning disable 1591

was just curious if it would be possible.

What is the actual question? Would you like to know another way to disable the warnings that are generated when the XML comments are missing? In the project's properties change to the "Build" tab and uncheck "XML documentation file". However, I'd suggest to not suppress the warnings but to add the missing documentation. — Gorgsenegger, Dec 15 '11 at 12:48
That is absolutely correct but was just curious about how if we can solve this from one place as i was new to this. — Nivid Dholakia, Dec 15 '11 at 14:29
These related questions may help: http://stackoverflow.com/questions/11444631/how-to-disable-a-particular-compiler-warning-for-a-particular-file http://stackoverflow.com/questions/3630282/vs2010-autogenerated-files-and-xml-documentation — Mightymuke, Jul 23 '12 at 03:24
The warning only appears for members that are visible to other assemblies. Often people make classes (and interfaces, enums, etc.) `public` for no good reason. In that case an easy (and in my opinion good) fix is to just remove the word `public` (or replace it with a redundant `internal` keyword, depending on preferred style) from the outermost enclosing type. Then all CS1591 warnings about this type and its members disappear. Of course you may still have to keep _some_ types `public`. But in that case it is fair that you require documenting their public parts properly. — Jeppe Stig Nielsen, Feb 23 '18 at 09:56

score 371 · Accepted Answer · edited Dec 08 '16 at 16:20

371

As suggested above, in general I don't think that these warnings should be ignored (suppressed). To summarise, the ways around the warning would be to:

Suppress the warning by changing the project Properties > Build > Errors and warnings > Suppress warnings by entering 1591
Add the XML documentation tags (GhostDoc can be quite handy for that)
Suppress the warning via compiler options
Uncheck the "XML documentation file" checkbox in project Properties > Build > Output
Add #pragma warning disable 1591 at the top of the respective file and #pragma warning restore 1591 at the bottom

edited Dec 08 '16 at 16:20

Max

846
1
9
26

answered Dec 16 '11 at 09:28

Gorgsenegger

7,356
4
51
89

221

Please, please don't use GhostDoc. If a comment can be inferred from the method name it can be inferred better by a human. This adds zero value. That time would be better spent congratulating yourself on a well-named method. – JRoughan Jun 29 '12 at 01:08
30

I have to disagree, GhostDoc helps me to quickly add the required list of paramaters and a return tag (if the method is not void). I do use and like it, and I know quite a few other people who also do. It is true, however, that the description in the summary might need some editing, but this counts for most automatisms in such cases. – Gorgsenegger Jul 01 '12 at 13:19
40

If all it did was add placeholders it would be a nice little time saver, but the number of codebases I've seen where developers leave the generated text makes we think we just aren't collectively mature enough to use it. Comments are a (often necessary) crutch for code that isn't self-documenting and by offering shortcuts this tool has a negative net benefit on the worlds code. – JRoughan Jul 03 '12 at 09:43
4

You can also use it in conjunction with StyleCop so you show e.g. XML comment tags without content as warnings. I do think it is quite a bold thing to say that self-documenting code should be sufficient and I disagree. Nevertheless, no IDE, tool or add-on should relieve the developer from the process of "thinking"... – Gorgsenegger Jul 03 '12 at 14:15
32

@JRoughan: I completely agree. The worst part is, when you finally find the time to properly document your code, these tools make it impossible to tell how thorough your real documentation coverage is. Any tool that calculates documentation coverage will always read 100%. So you literally have to go through the mentally exhausting task of reading *every* XML comment and evaluating whether it is sufficient to document the code. Having done this on a large project, I can tell you, it's not fun at all. Please people! Do not use these auto-documentation tools! – HiredMind Nov 30 '12 at 23:29
6

A tool is only as good as its users - if you use GhostDoc and then don't amend the generated documentation, it turns out as described by you above. For me and others in my team it works quite well, you can use the generated stuff and change as required. Of course, everyone should use what they prefer, but I wouldn't generally demonise it :) – Gorgsenegger Dec 03 '12 at 20:55
41

@Gorgsenegger: Not in this case. It is not the tool that's flawed, it's the entire concept. VS2012 adds method/parameter stubs to standardized XML comments if that is what you want. But adding comments that are simply longer versions of the method names and calling it documentation is just visual clutter. – HiredMind Jan 09 '13 at 06:13
3

@HiredMind VS2010 does this as well, I just wanted to add. The only reason to use GhostDoc is that is automatically copies the documentation from inherited methods, which is often enough if the interface is already well documented. – dialer Mar 11 '14 at 15:15
2

@dialer, then why doesn’t the documentation generator automatically inherit missing documentation? What if the interface’s documentation is updated leaving the implementors’ documentation stale? – binki Mar 19 '14 at 16:41
@binki If you're suggesting that Visual Studio lacks this feature, I completely agree with you. – dialer Mar 21 '14 at 10:35
pragma warning restore at the bottom of a source file might be optional. http://stackoverflow.com/q/556771/2498426 – Jerther Dec 08 '16 at 17:02
Is that possible to disable the warning for a specific folder in Visual Studio 2019 actually 16.6.5? – Marc Roussel Aug 04 '20 at 16:35

score 99 · Answer 2 · answered Dec 28 '16 at 07:44

99

Disable the warning: Go to the Project properties(Right click on your project and choose Properties from the context menu) Go to the Build tab

Add 1591 to the Suppress warnings textbox

answered Dec 28 '16 at 07:44

Rao Adnan

1,597
12
19

6

Works like a charm with comma-separated lists: "S125,CS1591,S1172". After a build the warings disappeared. – Andrei Drynov Jan 19 '17 at 14:22
20

Thanks for answering the question and not lecturing on whether or not to suppress the warnings! – Dalbir Singh Mar 16 '18 at 16:00
IMHO, this is the preferred option as it allows turning off for just projects that we don't want it, like unit tests, while keeping it for the others. – Michael Mar 26 '23 at 15:06

score 80 · Answer 3 · edited Mar 29 '20 at 19:22

80

You can also modify your project's .csproj file to include a <noWarn>1591</noWarn> tag inside of the first <PropertyGroup>. Originally from Alexandru Bucur's Article Here

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    ...
    <NoWarn>1591</NoWarn>
  </PropertyGroup>
  ...
</Project>

edited Mar 29 '20 at 19:22

Yodacheese

4,787
5
34
42

answered Jan 25 '19 at 19:52

DotNetPadawan

1,026
7
10

5

This should be the answear for current days. – Edgar Froes Feb 03 '19 at 02:31
6

Agreed. Most of the answers don't work with other editors, such as Visual Studio Code. – Krzysztof Czelusniak Feb 22 '19 at 17:05

score 15 · Answer 4 · edited Oct 17 '17 at 12:49

15

Go into project properties and uncheck the generate XML document option.

Recompile and the warnings should go away.

edited Oct 17 '17 at 12:49

wonea

4,783
17
86
139

answered Sep 23 '15 at 19:06

Chris

159
1
2

3

This is a good approach as long as you don't need to generate the XML docs and you don't mind that the XML comments won't be validated. – Keith Oct 10 '15 at 16:48
1

This does not work if you want to keep the warnings from files that are not auto-generated. Removing all warnings just to get rid of a subset of warnings seems a bit overkill to me. Besides, in most companies, it is common practice to actually create XML comments in all files that don't contain auto-generated code. Also, the user asked for a solution that does not simply remove the XML comment feature, so this does not answer the question. – SubliemeSiem Dec 10 '15 at 14:53
This helped me figure out why I was getting the warning about XML comments being disabled so I could fix it by checking the box, basically doing the opposite of what this Answer says. – computercarguy Nov 12 '20 at 16:16

score 8 · Answer 5 · answered Jan 27 '22 at 12:46

Visual Studio 2022:

I would recommend to use .editorconfig file in the Visual Studio to set a common code style across all solution.

In this case, just add this code manually to the .editorconfig file:

# SA0001: XML comment analysis is disabled due to project configuration
dotnet_diagnostic.SA0001.severity = none

NOTE: For me, suppressing SA0001 from the Editor Config designer not working.

Only manual setting rule in the file.

score 4 · Answer 6 · edited Oct 08 '20 at 04:40

4

This would have been a comment but I couldn't get it to fit the limitation:

I would love to disable them just for the Reference.cs and WebService imports. Actually, I'm using a macro to do it for a file. Just open the file and execute this macro (tested in VS2010):

Sub PragmaWarningDisableForOpenFile()
    DTE.ActiveDocument.Selection.StartOfDocument()
    DTE.ActiveDocument.Selection.NewLine()
    DTE.ActiveDocument.Selection.LineUp()
    DTE.ActiveDocument.Selection.Insert("#pragma warning disable 1591")
    DTE.ActiveDocument.Selection.EndOfDocument()
    DTE.ActiveDocument.Selection.NewLine()
    DTE.ActiveDocument.Selection.Insert("#pragma warning restore 1591")
    DTE.ActiveDocument.Save()
End Sub

There is really no way to do this automatically? You would have to redo this every time the auto-generated code overrides the file.

edited Oct 08 '20 at 04:40

Pang

9,564
146
81
122

answered May 08 '12 at 12:38

Kjellski

925
10
24

2

I think this warning shouldn't show up for auto-generated content, maybe you'll have to check the corresponding setting in the project's properties. – Gorgsenegger May 12 '12 at 12:57
1

Nope, it's all shown by just enabling XML-Comment warnings. And there is no such option to disable it just for autogenerated code. Therefor the snipped when you're in need of regenerating the code. – Kjellski May 12 '12 at 20:15
Under project properties `Code Analysis`, there is an option `Supress results from generated code`. Having to rerun a macro after each code regeneration isn't really a solution IMO. If the option above doesn't work for you, perhaps the code generator can be adjusted to automatically add the pragma directive instead? – Laoujin Mar 27 '13 at 14:39
@Laoujin thanks for your comment, but as I've mentioned I don't like this solution either. I can't see a reason for the downvote, I've used the setting you're mentioning without success. Any chance you try your solution for WebService imports? – Kjellski Mar 27 '13 at 21:30

score 3 · Answer 7 · answered Jan 31 '23 at 09:24

You can disable this selectively on a per-file basis using an .editorconfig file - for example, if you have a specific source file (or multiple files), you can use something like:

# single file
[IgnoreThisFile.cs]
dotnet_diagnostic.CS1591.severity = none

# multiple files, matching on specific naming convention
[*{Type,Stuff,Things}.cs]
dotnet_diagnostic.CS1591.severity = none

Note that I've had mixed experiences with consistently managing this warning but in the current version (17.4.4+) of VS2022, it seems to stick. Make sure the .editorconfig is at a "high" enough level in your folder structure that it applies across all of your source files (or alternatively, use multiple files at specific folder levels depending on your needs).

THIS is the answer I was looking for. I want everything in the solution documented _except_ for the classes that occur in *.designer.cs files, and this is, by far, the best current solution for that, in visual studio. And it's not as fragile or arcane as the SuppressMessageAttribute, and doesn't require the CODE_ANALYSIS symbol to be defined, like that attribute does. — dodexahedron, Jun 09 '23 at 21:36

score 1 · Answer 8 · answered Sep 09 '22 at 09:10

1

To fix a violation of this rule, enable the XML documentation file as part of the project output by adding true to your project file.

Mentioned at:

https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA0001.md#how-to-fix-violations

answered Sep 09 '22 at 09:10

Peeyush

4,728
16
64
92

This is not the same warning message. In fact, enabling the XML documentation is what causes the warning message to show up in the first place. – General Grievance Aug 22 '23 at 15:00

Visual Studio Disabling Missing XML Comment Warning

8 Answers8

Linked