[clang-tidy] Ideas on improving how static analyzer checks appear in the check list

[localspook]

There are two issues with the static analyzer docs right now:

1. The static analyzer checks appear only in the list of aliases. I'm worried that this might be a bit confusing and/or reduce their visibility; finding entirely new checks in the list of aliases is a bit unexpected. I propose moving them into the main check list.

2. When a user clicks on a static analyzer check, they get taken to a page which, after 5 seconds, redirects them to the static analyzer docs. There are two things they might see on that page:
   a) A single sentence description. 5 seconds is maybe enough to read and understand that, but a single sentence is quite uninformative.
   b) A whole paragraph. (example 1, example 2). 5 seconds is nowhere near enough to read that, and I expect everyone gets interrupted in the middle of it, which is really not good user experience.

I propose removing the redirect and linking to the static analyzer docs directly.

Thoughts?

[llvmbot]

@llvm/issue-subscribers-clang-tidy

Author: Victor Chernyakin (localspook)

There are two issues with the static analyzer docs right now:

1. The static analyzer checks appear only in the list of aliases. I'm worried that this might be a bit confusing and/or reduce their visibility; finding entirely new checks in the list of aliases is a bit unexpected. I propose moving them into the main check list.

2. When a user clicks on a static analyzer check, they get taken to a page which, after 5 seconds, redirects them to the static analyzer docs. There are two things they might see on that page:
   a) A single sentence description. 5 seconds is maybe enough to read and understand that, but a single sentence is quite uninformative.
   b) A whole paragraph. (example 1, example 2). 5 seconds is nowhere near enough to read that, and I expect everyone gets interrupted in the middle of it, which is really not good user experience.

I propose removing the redirect and linking to the static analyzer docs directly.

Thoughts?

[llvmbot]

@llvm/issue-subscribers-clang-static-analyzer

Author: Victor Chernyakin (localspook)

There are two issues with the static analyzer docs right now:

1. The static analyzer checks appear only in the list of aliases. I'm worried that this might be a bit confusing and/or reduce their visibility; finding entirely new checks in the list of aliases is a bit unexpected. I propose moving them into the main check list.

2. When a user clicks on a static analyzer check, they get taken to a page which, after 5 seconds, redirects them to the static analyzer docs. There are two things they might see on that page:
   a) A single sentence description. 5 seconds is maybe enough to read and understand that, but a single sentence is quite uninformative.
   b) A whole paragraph. (example 1, example 2). 5 seconds is nowhere near enough to read that, and I expect everyone gets interrupted in the middle of it, which is really not good user experience.

I propose removing the redirect and linking to the static analyzer docs directly.

Thoughts?

[LegalizeAdulthood]

I propose removing the redirect and linking to the static analyzer docs directly.

This sounds good to me.

[steakhal]

Sounds good to me.

[NagyDonat]

Sounds good to me as well, but I'm a bit concerned that the static analyzer docs may be a bit confusing for someone who expects to read about a Tidy check:

• In Tidy the names need to be prefixed with clang-analyzer- which is (naturally) not present in the analyzer docs.
• For many static analyzer checkers, the documentation also describes their configuration options -- but AFAIK there is still no way to set these when the checker is used through Tidy.

How can we handle these difficulties?

[LegalizeAdulthood]

How can we handle these difficulties?

We could leave the existing intermediate page there without the redirect.

[localspook]

In Tidy the names need to be prefixed with clang-analyzer- which is (naturally) not present in the analyzer docs.

Agreed, this could be confusing, and I can't think of an ideal solution for it. As an idea: maybe we could add a little note under each checker in the CSA docs like "Equivalent clang-tidy check: clang-analyzer-$CHECKER"? If a lot of users use CSA through clang-tidy (I don't know whether that's the case. Maybe most users use it through clang?), this could be helpful information.

For many static analyzer checkers, the documentation also describes their configuration options -- but AFAIK there is still no way to set these when the checker is used through Tidy.

I believe clang-tidy does expose these options. You can put in .clang-tidy something like:

CheckOptions:
  clang-analyzer-optin.performance.Padding:AllowedPad: 20

https://godbolt.org/z/nrW1adYqq