Analyzer docs should explain "why"

[kellyelton]

The analyzer docs contain the same info you can find inside of visual studio, so clicking to see more details of any RCS number serves no practical purposes at the moment.

[josefpihrt]

The analyzer docs contain the same info you can find inside of visual studio, so clicking to see more details of any RCS number serves no practical purposes at the moment.

This is not true. Each page contains code sample (code with diagnostic, code with fix), some pages contains description (RCS1224) and some pages contains links (RCS1242).

Many analyzers do not need any extra information (are self-explanatory).

If you want to improve documentation

• you can do it by following these instructions
• or you have make specific suggestion (i.e. "I would like to see additional description for analyzer RCSxxxx").

Frankly, I think that documentation for Roslynator is better than most of other similar projects.

[kellyelton]

Thanks for the reply. I may have only stumbled across documents that weren't helpful to me at the time.

I don't remember the exact analyzer that caused me to create this issue, I just know this isn't the first time I've ran into this issue.

I did a little bit of searching through the docs and I will say that most that I saw are in pretty good shape like you said. It also seems that the newer analyzers contain more details which is nice to see.

There are so many analyzers to go through, and I decided not to look through them all, but here's one example I've found.

https://github.com/JosefPihrt/Roslynator/blob/master/docs/analyzers/RCS1231.md RCS1231: Make parameter ref read-only Why? (It's not obvious if you only look at the document, and there are no links to additional sources)

Going forward, if I stumble across one that needs more clarification or anything, I'll create an issue specific to that.

Thanks again for the reply.

[marcospgp]

In my experience most warnings are not very clear indeed:

I've previously worked with code checkers like ESLint for Javascript, and the text was much more helpful. In this case for example, it would say something like "Fields that aren't modified by code should be declared as readonly.".