roslyn: Proposal: Disable CS1591 "Missing XML comment" on generated code

Unfortunately the notion of generated code is generally a heuristic instead of a solid item. There are too many attributes / conventions to account for. That makes it harder for us to change compiler behavior based on it.

Additionally there is a very simple work around for generators who explicitly don’t want this warning. Simply generate the following into the code file:

#pragma warning disable 1591

I strongly disagree. You will catch 95% of the issues by checking for the text “auto-generated” at the start of the module.

@SolalPirelli @Portikus I filed internal bug AB#451278 for the XAML compiler warnings:

On a side note, it also makes “Treat Warnings as Errors” completely useless too. (i.e. if you use out of the box settings, turn on treat warnings as errors, and XML documentation – it will be impossible to compile your project without manually editing the generated code files).

What kind of project are you working in?

UWP libraries

What specific warnings are you seeing that you would like to avoid?

CS1591 “Missing XML comment”

What is the source of the file where the warning appears

XamlTypeInfo.g.cs generated by UWP tools for XAML files.

It would be great to have #pragma generated or something like that that’s clearer about intent.

Why not GeneratedCodeAttribute? It already exists. (although I have no idea if it’s in .NET Standard)

What kind of project are you working in?

UWP Libraries and Apps

What specific warnings are you seeing that you would like to avoid?

CS1591 “Missing XML comment”

What is the source of the file where the warning appears

*.g.cs like MainPage.g.cs e.g for the Method “GetBindingConnector”. Reproduce: Just create a Blank App in Visual Studio 2017 and check the checkbox XML documentation file.

If I were the one generating the code, sure, but in the case of UWP XAML, it’s definitely not me… Otherwise I might as well generate the XML doc.

Add suppress to the end of editorconfig with desired file mask work for me

# resource files
[*.Designer.cs]
dotnet_diagnostic.CS1591.severity = none

This is also affecting System.Text.Json source generated code using JsonSerializerContext.

[JsonSerializable(typeof(Foo[]))]
public partial class CustomJsonSerializerContext : JsonSerializerContext
{
}

More info at:

• https://github.com/dotnet/core/issues/6897

I highly recommend supporting the GeneratedCodeAttribute, and <auto-generated />, because it’s what most libraries and code generation tools use today. – It does us no good to tell us to add a #pragma warning disable 1591 or any other #pragma directive for that matter, since we’re obviously powerless to edit the generated code. 😦

Adding a new pragma and telling us to use that, in the BEST case, means, that if you implement it today, our pain will go away in about 5 years (or later; i.e. as soon as the other MS teams start adding the #pragma). – At the worst case, it’s just another way to mark code as generated, and just another thing that the tools will have to check for. – It’s seriously an annoying proposition.

To my knowledge, you can’t suppress CS1591 in the global suppressions file – the VS 2015 tooling definitely won’t give you the option anyway; it will only suppress with a #pragma directive for CS warnings. – And obviously we don’t want to turn the warning off for a whole project – Just because MS isn’t documenting their code anymore, doesn’t mean we don’t want to document ours! 😦

SimpleStubs.generated.cs from SimpleStubs version 2.3.3.

@Portikus I would recommend you disable CS1591 and CS1573 in test projects using one of the strategies documented in the How to fix violations section of StyleCop Analyzers rule SA0001. If you cannot do that for some reason, then the solution here would be:

1. Request SimpleStubs add a #pragma warning suppress 1591 to the generated code
2. Use a GlobalSuppressions.cs file in your test project to selectively disable CS1591 on that generated code

Additionally there is a very simple work around for generators who explicitly don’t want this warning. Simply generate the following into the code file: #pragma warning disable 1591

Have you ever worked with Windows 8 or Windows 10? There’s a significant chunk of code that’s generated by Visual Studio in order to get around the limitations of the RTL and that all gets regurgitated back at you when you build because of this ‘feature’. It becomes a nightmare to filter out the real warnings and errors from the XML document warnings. You should really work in this environment before you close the case out. This is a bug and there’s no workaround.

Did this ever get resolved? I’ve got a situation where I want to ignore this diagnostic under certain namespaces but let it report under others. I tried using a custom diagnostic suppressor but it’s the first I’ve ever written so I’m not sure if I’m doing anything wrong (can it just live in the same project?) or it’s just that I’m falling into the same bucket as:

The global suppressions file can be used to suppress warnings reported by analyzers, but not ones reported by the compiler.

Seriously, the people that make these decisions do not develop for UWP.

This is a fascinating and common problem which is definitely not unique to this team or even to this company. Back when I worked in the game industry, it always amazed me how much better the players were at the games than the creators of the game who “know everything about it”. Yet the explanation was simple: the time it took the creators to make the game was time taken away from them practicing playing it.

Every day I work with several tools and workflows to solve problems, yet I know that I’m only exercising a minute, almost insignificant, fraction of the use cases these tools are built to handle. I love reading about other workflows and the successes and challenges users have in them. Sometimes the reports involve something simple that we can just fix, and other times the reports require a lot of effort to understand a workflow that substantially deviates from our “comfort zone”. Even though they can take a great deal of discussion before we figure out what to do, the latter are actually some of my favorite issues because they challenge the way I view daily developer activities and the ideas we put forward in attempts to improve everyone’s productivity.

tl;dr: I don’t know what the final fix to the issues presented above will be, but I am definitely interested in the problem space and want to see the pain points resolved.

Why not GeneratedCodeAttribute? It already exists. (although I have no idea if it’s in .NET Standard)

I don’t actually feel super invested in what exactly we have to do to codegen-wise to accomplish this. The Roslyn folks are in the best position to come up with a solution.

The docs for #pragma say:

#pragma gives the compiler special instructions for the compilation of the file in which it appears.

This seems the cleanest to me because it’s not entangled with any other language features and is file-centric. But this is just me doing backseat language design. I’d be satisfied with anything other than playing whackamole with future warnings.

@SolalPirelli The attribute can’t be used to distinguish very well between generated code in a partial class and user code for the same class in a different file. For StyleCop Analyzers 1.0 (which handled its own generated code detection) we removed all special cases related to this attribute for a big performance win. I’m concerned that in 1.1 we may have introduced a performance regression by allowing Roslyn (which checks this attribute) to check this for us, so I may end up needing to remove the special cases for it there too (for StyleCop Analyzers, not for all analyzer projects).

To add my feedback to this issue, as an owner of a code generator (ASP.NET Core Razor) this doesn’t scale for us when warnings like CS1591 are part of the project’s configuration.

We can’t test for (and react to) every way that users can have their project configured. If more of these kinds of warnings are going to be added in the future (based on project settings, not related to the correctness of code) then it just makes more work for tool authors.

It would be great to have #pragma generated or something like that that’s clearer about intent. Yeah yeah, I know.

Actually, I just got through looking at Sam’s suggestion. Turns out I created a similar solution and posted it as a NuGet package. You can check it out at:

https://www.nuget.org/packages/IgnoreGeneratedFilesBuildTask/

What kind of project are you working in?

.NetStandard

What specific warnings are you seeing that you would like to avoid?

CS1591 “Missing XML comment”

What is the source of the file where the warning appears

SimpleStubs.generated.cs from SimpleStubs version 2.3.3. https://www.nuget.org/packages/Etg.SimpleStubs/ https://github.com/Microsoft/SimpleStubs

Sam, would you please explain to us why disabling 1591 whenever you see <auto-generated> in the header of a file won’t solve 95% of the issues here.

Amen. This is a big issue for Windows 8/10 development, especially with the generated code for type information.

This happens with settings files too (and a bunch of other places), it’s extremely annoying, as we have no power to comment those files, and I really don’t want to turn off CS1591. – In that case, the only thing that makes sense is to disable the warning for those files (because how would the generator know what comment to put for my custom settings?).

I would prefer the XML documentation to be generated instead.