search

DotNetAnalyzers / StyleCopAnalyzers

An implementation of StyleCop rules using the .NET Compiler Platform
MIT License
2.65k stars 508 forks source link

SA1600 and friends are reported even though the project does not produce XML documentation output #3097

Open RobSiklos opened 4 years ago

RobSiklos commented 4 years ago

I have a project (C#, net472, new "sdk" csproj format) which does not generate any documentation XML output. Because of this, I get SA0001:XmlCommentAnalysisDisabled, as expected.

However, what I don't expect (and what I'm seeing) is that I still have a bunch of SA documentation warnings (1600, 1604, 1611, 1623, 1629, etc) reported by StyleCopAnalyzers.

According to the docs for SA0001:

All diagnostics of XML documentation comments has been disabled

however, this is clearly not the case if 1600 and friends are being reported.

I have a bunch of projects which are plugins/extensions for another system, so much of the stuff needs to be public, but it's not exposed as a public API, so I don't want all these rules checked on all those projects.

Sure, I could use a ruleset file to disable the rules, but based on the docs for SA0001, I shouldn't have to do this.

Am I missing something here?

RobSiklos commented 4 years ago

@sharwell Can you please clarify the expected behaviour here?

rdeago commented 4 years ago

DISCLAIMER: I have no intimate knowledge of Roslyn, and I'm sorry if this comment looks like a Dunning-Kruger fit. I don't think I'm smarter than anyone; just trying to lend a hand, or better, a pair of eyes.

In trying to understand this issue better, I had a look at the relevant analyzers' source code and found this check in SA1600, SA1601, and SA1602 analyzers. I have three quick questions:

  1. Why if (context.GetDocumentationMode() == DocumentationMode.None)? Could if (context.GetDocumentationMode() < DocumentationMode.Diagnose) be more suitable?

  2. The GetDocumentationMode extension method returns DocumentationMode.Diagnose if it cannot obtain a value because of a null SyntaxTree. Isn't that default too aggressive?

  3. Why are there no such checks in ElementDocumentationBase and ElementDocumentationSummaryBase?

sharwell commented 4 years ago

I think a more accurate description of SA0001 would be:

Diagnostics for documentation comments may be missing or incorrect, and code fixes for all diagnostics may misbehave in source files containing any documentation comments.

RobSiklos commented 4 years ago

@sharwell I guess that's an accurate description for the current behaviour. However, is that the desired behaviour?

My vote would be that the existing documented behaviour (All diagnostics of XML documentation comments has been disabled) is the expected behaviour.