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

[Aaron Ballman via cfe-dev]

On Tue, Oct 6, 2015 at 12:50 PM, Richard via cfe-dev
<cfe-dev at lists.llvm.org> wrote:
>
> [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.

Depending on the license for the documentation itself, we would have
to obtain permission from the copyright owners to do this, which could
severely limit what docs we can include.

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

Tip of Tree (latest trunk svn version).

~Aaron

>
>> - 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>
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev