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

[Aaron Ballman via cfe-dev]

On Wed, Oct 7, 2015 at 4:24 PM, Daniel Jasper via cfe-dev
<cfe-dev at lists.llvm.org> wrote:
> 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.

Strongly agreed.

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

We solved this for Clang's attributes by table-generating the
documentation and generating the web view server-side. We've also
discussed using the same machinery to drive documentation for clang
driver options. I think we could use a similar thing for clang-tidy (I
am still in favor of table-generating a lot of the machinery that we
currently use python scripts to generate for us).

~Aaron

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