Roslyn-analyzers: Consider moving the generic analyzer docs out of Visual Studio

[roji]

The repo README points to this page as the docs on code analysis - this section is under the Visual Studio product docs. However, most of the docs are general C#/.NET docs, which seem like they should reside in a more generic place (e.g. the C# docs).

I honestly had a moment's hesitation if I was looking at a VS feature that wouldn't work on the command-line or VS Code/Rider - I'm sure newcomers find this confusing.

On a related note, getting started with the Microsoft.CodeAnalysis.NetAnalyzers rules is difficult. The default severity of the rules isn't documented in the reference (#4179), and I spent some frustrating time wondering why CA2016 wasn't appearing on the command-line before realizing it's not a warning/default by default and needs to be configured. Getting the predefined ruleset/editorconfig files is also Windows- and VS-specific, with instructions to go to %USERPROFILE%\.nuget\packages\microsoft.codeanalysis.netanalyzers\<version>\editorconfig etc.

[mavasani]

The repo README points to ]this page](https://docs.microsoft.com/visualstudio/code-quality/roslyn-analyzers-overview) as the docs on code analysis - this section is under the Visual Studio product docs. However, most of the docs are general C#/.NET docs, which seem like they should reside in a more generic place (e.g. the C# docs).

The rules are not specific to C# or VB, but we should potentially move all generic analyzer related docs to dotnet docs, and we do plan to move all CA rule docs to dotnet docs repo soon. The core issue with moving all analyzer/code analysis related docs to dotnet docs is lot of these existing docs need to show how users can easily accomplish things using tooling in VS. Ripping these into two separate docs that cross reference across repos would be significant work for docs team, though possible.

Tagging @gewarren @mikadumont @Mikejo5000 for their views. Also we likely need to move this issue to one of the docs repo for visibility.

[mavasani]

On a related note, getting started with the Microsoft.CodeAnalysis.NetAnalyzers rules is difficult. The default severity of the rules isn't documented in the reference (#4179), and I spent some frustrating time wondering why CA2016 wasn't appearing on the command-line before realizing it's not a warning/default by default and needs to be configured.

There are couple of big issues related to specifying default severity for each CA rule in its docs page:

1. There are multiple ship vehicles for these CA rules, each with potentially different severity/enabled by default value:

   1. Microsoft.CodeAnalysis.FxCopAnalyzers package
   2. Binary FxCop, which is still supported for older VS versions.
   3. .NET SDK

2. The values of these default severity/enabled by default are very likely to keep changing with each version of .NET SDK, so we would either need version specific section whenever these change OR always specify the latest value in upcoming version, though that can be confusing.

I’ll let @gewarren @mikadumont chime in as this would be a pretty big doc commitment.

[mavasani]

Getting the predefined ruleset/editorconfig files is also Windows- and VS-specific, with instructions to go to %USERPROFILE%.nuget\packages\microsoft.codeanalysis.netanalyzers\\editorconfig etc.

That is a good point, which should be kept in mind if/when moving this section to dotnet docs repo.

[roji]

Thanks for all the details, I mainly wanted to highlight some experience issues I had as a Linux user starting to use these for the first time.

Ripping these into two separate docs that cross reference across repos would be significant work for docs team, though possible.

As a suggestion, maybe the reference docs should at least be split out as they don't seem to be connected to the VS parts - they simply describe the rules etc. I can see that the rest may be tricky, but hopefully some way can be found to explain this to non-VS users as well.

There are couple of big issues related to specifying default severity for each CA rule in its docs page:

If that's the case, it may be worth clearly specifying that up-front, and making sure users understand that they don't automatically get everything as warnings/errors just because they target net5.0 (or add <AnalysisLevel>latest</AnalysisLevel>).

[Evangelink]

The values of these default severity/enabled by default are very likely to keep changing with each version of .NET SDK, so we would either need version specific section whenever these change OR always specify the latest value in upcoming version, though that can be confusing.

I think there is already a similar problem with rule docs. When we change the default behavior of a rule or introduce a new user option the doc doesn't state at which point it became available. We could add this info or we could also have some kind of drop down to select the version and display the "right" doc page.

[Mikejo5000]

@roji @mavasani Current plan is to move the IDE-agnostic docs (like the overview you referenced) to the .NET docs.

[Evangelink]

@mavasani Looks like this can be closed, doc is no longer under the Visual Studio hood.