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

[Daniel Jasper via cfe-dev]

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.
2. For ToT, we cannot control how external docs are changed.
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.


>
>
>>
>> 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/bcb55737/attachment.html>