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

[Gábor Horváth via cfe-dev]

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.

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