search

dotnet / roslyn

The Roslyn .NET compiler provides C# and Visual Basic languages with rich code analysis APIs.
https://docs.microsoft.com/dotnet/csharp/roslyn-sdk/
MIT License
18.88k stars 4.01k forks source link

CS1591 is fired on source generated code #54119

Open chsienki opened 3 years ago

chsienki commented 3 years ago

On a project with the /doc: option enabled, the compiler will issue a warning on code that is coming from a generated file. (see https://github.com/dotnet/runtime/pull/53275)

A user can suppress the issue via a .globalconfig, but has no other recourse to fix the issue. Should we not fire CS1591 for generated code, or is it still a useful indicator to the user that types in their public API are going to have no documentation?

sharwell commented 3 years ago

Related to #41171

chsienki commented 3 years ago

Note this still occurs if the file correctly marks itself as generated via any of the heuristic methods.

Youssef1313 commented 3 years ago

I don't see why the compiler shouldn't issue the warning?

If the generated type is partial, then this could be a duplicate of https://github.com/dotnet/roslyn/issues/54103, and isn't specific to source generated files. Otherwise, then the compiler is correct about issuing a diagnostic IMO.

Youssef1313 commented 2 years ago

@chsienki Can you check if https://github.com/dotnet/roslyn/pull/56419 resolves this?

Youssef1313 commented 2 years ago

I see there are other aspects than what #56419 solves. (e.g: https://github.com/dotnet/runtime/issues/61379). But I think generator authors should produce a #pragma warning disables or properly generate documentation comments.

Not much convinced the compiler should special case generated code here.

jcouv commented 2 years ago

This was also reported regarding [JsonSerializable] (in https://github.com/dotnet/roslyn/issues/60533). We should either have the source generator produce documentation, or do a compiler-level solution. Will chat offline

nabond251 commented 1 year ago

FWIW, I'm one of those odd birds that makes the compiler treat warnings like errors. Admittedly bit of a hardline approach, but muh code quality. Such draconian practices are duly rewarded by this breaking build.

mwasplund commented 1 month ago

Can we get an answer as to whether this warning should respect *.generated.cs or \? I do not want generated code to pollute my build output with warnings. I do not have control over this code and therefore do not want style warnings like this XML warning to show up. As @nabond251 called out, this punishes folks that like to enforce code style using warnings as errors.