RFC: Clang-tidy check documentation for aliases shouldn't redirect when additional information is given

We have pages for check aliases that say “this check is an alias of XXYYZ check” and then they redirect to the XXYYZ page. There is also an explicit link to the XXYYZ check page, presumably for browsers that don’t allow automatic redirects.

However, some of these pages have additional information such as links to CERT guidelines or links to additional checks for reference. When the 5 second redirect is in play, you could be reading this additional information and then it disappears off the page because the browser honors the redirect request.

I propose that alias pages that contain additional links or information should not automatically redirect to the check for which this check is an alias.

I agree with the problem. As a first step we could disable the redirect and provide a link for users to click manually.

Personally, I quite dislike the idea of “alias” being exposed to the user. IMHO this is just an implementation detail to avoid code duplication that the user shouldn’t need to be concerned with.

In that sense, as a user I would expect the doc of each check to be self-contained without having to redirect to another page. This might be possible to implement by including a common piece of documentation into each of the alias checks’ documentation, followed by the check-specific documentation. What do you think?

Currently, users need to know about aliases in order to avoid running the check twice.

Sure, but that info is still available in the main page that lists all checks, right? Having each check’s documentation self-contained without redirections is compatible with that.

In short, no it wouldn’t be better to replicate the documentation for the aliased check into the alias.

Details:

Replicating the documentation for an alias to be a complete copy of the aliased check would make matters more complicated than they already are because the documentation source files aren’t just inspected and edited by humans, they are also inspected by the add_new_check.py script and the presence of the redirect is how the script recognizes that a check is an alias of another check in order to build the list of aliases.

The whole alias mechanism has other problems related to it, for instance see this thread about how the aliases to the static analyzer checks are maintained in the docs. There are also these reviews that attempted to bring more order to the alias picture, but haven’t quite succeeded to the point of being accepted:

  • D114317 [clang-tidy][WIP] Do not run perfect alias checks
  • D72566 [clang-tidy] Clang tidy is now alias aware

Thanks, I wasn’t aware of that. I suppose it would be possible to update add_new_check.py to detect aliases matching some other text than the redirect link. But it might not be worth putting the effort if anyway the concept of alias might go away in the future?

Then simply removing the automatic redirect would be a simple fix providing good enough value, as you propose.

Argh, I hadn’t considered that removing the redirect would bust the script’s check for aliases. D’oh! Yay for discussing before hacking :).

So if we were to leave add_new_check.py unmodified, what should happen is that the secondary information on the redirect pages should be moved to the check that is aliased. That’s what I did with cppcoreguidelines-macro-to-enum – the links to the core guidelines are on the base check modernize-macro-to-enum.

I think this points out that the whole ad hoc approach to aliases generates lots of secondary issues and that aliases should be more explicitly declared in the code base somehow. For instance, just a method called registerAlias that delegates to the existing registerCheck would be a good start.