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

Thu Oct 8 07:37:59 PDT 2015

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

For my needs at CERT, we use Confluence which has similar
functionality. Even a static versioning scheme (like what LLVM uses
with http://llvm.org/releases/3.7.0/docs/index.html) would be fine.

How would you envision the release process working? Who would be
responsible for getting the specific versions for each release? Would
we require an automated process for retrieving these versions before a
checker module can link to 3rd party docs?

>>
>> 2. For ToT, we cannot control how external docs are changed.
>
>
> I think if we do (1), we can.

I think we would have to explicitly require that only versioned
documentation can be supported. It doesn't have to be hashes, it could
be any version-specific link. But it would be a problem to link to
unversioned documentation.

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

To know whether we want to do that or not depends on how you envision
surfacing these links. Are you thinking:

foo/bar/baz.cpp:3:24 warning: do not use const_cast
[cppcoreguidelines-pro-type=const-cast]
[https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#-type3-dont-use-const_cast-to-cast-away-const-ie-at-all]

(Note, that link doesn't contain the hash, and so would be
considerably longer in practice for the static documentation.)

If so, I don't think we can get away with anything *but* shortened
links. Looking at that diagnostic, 21 characters for actual guidance
to the user, 21 characters of location information, 39 characters to
identify the checker, and 132 characters to tell the user where to go
for more documentation. That's a whole lot of text to throw out to a
user.

Or do you have other ideas on how to surface the feature?

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