[cfe-dev] How to link to "more docs" for clang-tidy checks

[Aaron Ballman via cfe-dev]

On Tue, Oct 6, 2015 at 10:53 AM, Manuel Klimek <klimek at google.com> wrote:
> RFC:
> Often, clang-tidy diagnostics leave you standing in the rain - someone
> claims what you just did is a bad idea, but there is neither a fixit
> provided, nor do you understand why there might be a problem.
>
> Especially as we delve into the realm of more, um, controversial checks
> (cpp-core-guidelines), links to more documentation would be sometimes
> beneficial.

I think this is a great idea, if we can work it.

> The question is if / how we'd best link to more docs from clang-tidy
> diagnostics.
>
> Requirements are:
> - for a single clang release, the docs should be static (we don't want the
> docs to not reflect the checks)

Agreed.

> - for ToT, the docs shouldn't change unless we either verify that the
> updates are purely doc-fixes, or the code has changed to reflect the new
> docs

Agreed.

> - links need to be short, otherwise diags get too chatty

Agreed.

I would suggest adding on the following requirements:

- The links have to be something we control redirects to (so we can
consistently deal with fixing broken links without issuing a new
release of clang-tidy).
- The links have to be able to handle rebranding of diagnostics. For
instance, cert-dcl59-cpp would have a link to CERT's documentation,
but that should not be reflected in google-build-namespaces, which is
what provides the implementation for cert-dcl59-cpp.
- The links should be tied to the specific diagnostic instances
instead of the checker as a whole (so that one checker providing two
diagnostics can have separate links for each diagnostic).

> One possible solution would be to create a simple link-forwarding service on
> llvm.org (some JS inside a doc file), that will rewrite links into which we
> can encode whatever we want (revision, link-stamp, whathaveyou) to the
> relevant upstream docs (mostly github pages at a certain git hash).
>
> Thoughts? Am I crazy?

I think this is a great idea! One question: how do you envision
updating the ToT documentation to be the static documentation? Is that
a manual process we go through as part of the release checklist, or is
that an automated process we go through as part of the release
checklist?

~Aaron