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

[Richard via cfe-dev]

[Please reply *only* to the list and do not include my email directly
in the To: or Cc: of your reply.  Thanks.]

In article <CAOsfVv=sC9yW4wZbKkvP9LyqEGvMXRCLgBwuN2OunqkVsrCiDQ at mail.gmail.com>,
    Manuel Klimek via cfe-dev <cfe-dev at lists.llvm.org> writes:

> The question is if / how we'd best link to more docs from clang-tidy
> diagnostics.

I was discussing with Alexander Kornienko about how to include the
documentation in the clang-tidy executable itself so that I could ask
clang-tidy to describe a particular check for me.  If the
documentation were in clang-tidy's executable/distribution then I
would I need to worry about link forwarding services and so-on?  Is
this a simpler solution?

> Requirements are:
> - for a single clang release, the docs should be static (we don't want the
> docs to not reflect the checks)

Including docs in the distribution would do this.

> - 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

I don't know what "ToT" means.

> - links need to be short, otherwise diags get too chatty
> 
> 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).

If you don't include docs in the distribution but instead spit out
links, then yes you need a link forwarding service in order to get
stable URLs.
-- 
"The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
     The Computer Graphics Museum <http://ComputerGraphicsMuseum.org>
         The Terminals Wiki <http://terminals.classiccmp.org>
  Legalize Adulthood! (my blog) <http://LegalizeAdulthood.wordpress.com>