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

[Daniel Jasper via cfe-dev]

I have discussed this somewhat with Alex in the past and I think we should
wait for him to comment on this before doing anything. He is on vacation,
but should be able to comment in about two weeks.

I think we should first solve the internal documentation problem, i.e.
consider how we link to 3rd party documents later. For me, the important
question is where the documentation should actually live. I would prefer it
to live in the source files itself. This makes it easier to have a proper
versioning of the documentation and ensure that code changes are
accompanied by corresponding documentation changes. Furthermore, if we put
the documentation into a string in the source file, we can actually make
something like "clang-tidy -describe X" as well as "clang-tidy
-verbose-messages" work (the former just displaying the documentation for
check X, the latter printing out the full documentation of checks warning
on specific errors).

I agree that it would additionally be useful to extract the documentation
from the checks and put them behind a short link that we can attach to all
the messages. I can see various ways to do this, but I think we should
first decide whether it makes sense to put the documentation into (a string
in) the source code itself.

On Tue, Oct 6, 2015 at 8:04 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 <
> CAAt6xTvNGQNBYNj8i0T-jgk3urwuUtjFt6gbbT-tDRdnFm2Uiw at mail.gmail.com>,
>     Aaron Ballman via cfe-dev <cfe-dev at lists.llvm.org> writes:
>
> > On Tue, Oct 6, 2015 at 1:12 PM, Richard via cfe-dev
> > <cfe-dev at lists.llvm.org> wrote:
> > > I'm confused.  We're talking about the documentation for clang-tidy
> > > checks, which is wholly within the LLVM.org's ownership as it is part
> > > of their source tree.
> > >
> > > Why would we be limited in any respect on these docs?
> >
> > I was under the impression that we were talking about *external*
> > documentation, such as C++ Core Guidelines or the CERT C++ Coding
> > Standard.
>
> Ah.
>
> These would be supporting supplementary material to the clang-tidy
> documentation.
>
> For that, we're back to providing links and using a link redirection
> mechanism I suppose.
>
> In my email to Alexander, I was thinking along the lines of how cmake
> provides command-line switches to print out all of the documentation
> for everything that is in cmake.  They don't need to link to external
> 3rd party documents, however.
> --
> "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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20151007/99f9e9cf/attachment.html>