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

[Manuel Klimek via cfe-dev]

On Wed, Oct 7, 2015 at 10:42 PM Daniel Jasper <djasper at google.com> wrote:

> On Wed, Oct 7, 2015 at 10:32 PM, Manuel Klimek <klimek at google.com> wrote:
>
>>
>>
>> On Wed, Oct 7, 2015 at 10: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.
>>>
>>> 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.
>>>
>>
>> Note that this discussion is about links to external documentation, like
>> the C++ core guidelines.
>>
>
> Then I don't understand your requirements:
> 1. We cannot guarantee that external docs are static.
>

We can if they are on github through the use of a git hash.


> 2. For ToT, we cannot control how external docs are changed.
>

I think if we do (1), we can.


> 3. Links don't need to be short as we can link to the external docs from
> internal docs instead of linking to external docs directly.
>

Whether we always want to do that is one question I'd like to discuss.


>
>
>>
>>
>>>
>>> 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
>>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20151007/c0cdb10b/attachment.html>