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

[Manuel Klimek via cfe-dev]

On Tue, Oct 6, 2015 at 5:04 PM Gábor Horváth <xazax.hun at gmail.com> wrote:

> Hi!
>
> I do agree that, it would be awesome to have direct links to docs. An
> alternative way of doing this would be to distribute the static
> documentation with the release, and have a utility script that translates
> the checker name to a link to the local documentation and opens it up in
> the browser. The downside is that the diag message would not contain the
> link directly, so the users might miss the possibility of looking at the
> documentation for the checkers unless they read about the doc viewer script
> first.
>
> I think having short links in the diag messages while we want to avoid
> collisions might be a big challenge.
>

Would you suggest to bundle external docs (cppcoreguidelines) with our
release?


>
> Regards,
> Gabor
>
> On 6 October 2015 at 16:53, Manuel Klimek via cfe-dev <
> cfe-dev at lists.llvm.org> wrote:
>
>> RFC:
>> Often, clang-tidy diagnostics leave you standing in the rain - someone
>> claims what you just did is a bad idea, but there is neither a fixit
>> provided, nor do you understand why there might be a problem.
>>
>> Especially as we delve into the realm of more, um, controversial checks
>> (cpp-core-guidelines), links to more documentation would be sometimes
>> beneficial.
>>
>> The question is if / how we'd best link to more docs from clang-tidy
>> diagnostics.
>>
>> Requirements are:
>> - for a single clang release, the docs should be static (we don't want
>> the docs to not reflect the checks)
>> - for ToT, the docs shouldn't change unless we either verify that the
>> updates are purely doc-fixes, or the code has changed to reflect the new
>> docs
>> - links need to be short, otherwise diags get too chatty
>>
>> One possible solution would be to create a simple link-forwarding service
>> on llvm.org (some JS inside a doc file), that will rewrite links into
>> which we can encode whatever we want (revision, link-stamp, whathaveyou) to
>> the relevant upstream docs (mostly github pages at a certain git hash).
>>
>> Thoughts? Am I crazy?
>> Cheers,
>> /Manuel
>>
>> _______________________________________________
>> 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/20151006/ee94874b/attachment.html>