<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Oct 7, 2015 at 10:32 PM, Manuel Klimek <span dir="ltr"><<a href="mailto:klimek@google.com" target="_blank" class="cremed">klimek@google.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><br><br><div class="gmail_quote"><span class=""><div dir="ltr">On Wed, Oct 7, 2015 at 10:24 PM Daniel Jasper via cfe-dev <<a href="mailto:cfe-dev@lists.llvm.org" target="_blank" class="cremed">cfe-dev@lists.llvm.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div>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.</div><div><br></div><div>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).</div><div><br></div><div>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. </div></div></blockquote><div><br></div></span><div>Note that this discussion is about links to external documentation, like the C++ core guidelines.</div></div></div></blockquote><div><br></div><div>Then I don't understand your requirements:</div><div>1. We cannot guarantee that external docs are static.</div><div>2. For ToT, we cannot control how external docs are changed.</div><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_quote"><div><div class="h5"><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Oct 6, 2015 at 8:04 PM, Richard via cfe-dev <span dir="ltr"><<a href="mailto:cfe-dev@lists.llvm.org" target="_blank" class="cremed">cfe-dev@lists.llvm.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span><br>
[Please reply *only* to the list and do not include my email directly<br>
in the To: or Cc: of your reply. Thanks.]<br>
<br>
</span>In article <<a href="mailto:CAAt6xTvNGQNBYNj8i0T-jgk3urwuUtjFt6gbbT-tDRdnFm2Uiw@mail.gmail.com" target="_blank" class="cremed">CAAt6xTvNGQNBYNj8i0T-jgk3urwuUtjFt6gbbT-tDRdnFm2Uiw@mail.gmail.com</a>>,<br>
<span> Aaron Ballman via cfe-dev <<a href="mailto:cfe-dev@lists.llvm.org" target="_blank" class="cremed">cfe-dev@lists.llvm.org</a>> writes:<br>
<br>
</span><span>> On Tue, Oct 6, 2015 at 1:12 PM, Richard via cfe-dev<br>
> <<a href="mailto:cfe-dev@lists.llvm.org" target="_blank" class="cremed">cfe-dev@lists.llvm.org</a>> wrote:<br>
</span><span>> > I'm confused. We're talking about the documentation for clang-tidy<br>
> > checks, which is wholly within the LLVM.org's ownership as it is part<br>
> > of their source tree.<br>
> ><br>
> > Why would we be limited in any respect on these docs?<br>
><br>
> I was under the impression that we were talking about *external*<br>
> documentation, such as C++ Core Guidelines or the CERT C++ Coding<br>
> Standard.<br>
<br>
</span>Ah.<br>
<br>
These would be supporting supplementary material to the clang-tidy<br>
documentation.<br>
<br>
For that, we're back to providing links and using a link redirection<br>
mechanism I suppose.<br>
<br>
In my email to Alexander, I was thinking along the lines of how cmake<br>
provides command-line switches to print out all of the documentation<br>
for everything that is in cmake. They don't need to link to external<br>
3rd party documents, however.<br>
<div><div>--<br>
"The Direct3D Graphics Pipeline" free book <<a href="http://tinyurl.com/d3d-pipeline" rel="noreferrer" target="_blank" class="cremed">http://tinyurl.com/d3d-pipeline</a>><br>
The Computer Graphics Museum <<a href="http://ComputerGraphicsMuseum.org" rel="noreferrer" target="_blank" class="cremed">http://ComputerGraphicsMuseum.org</a>><br>
The Terminals Wiki <<a href="http://terminals.classiccmp.org" rel="noreferrer" target="_blank" class="cremed">http://terminals.classiccmp.org</a>><br>
Legalize Adulthood! (my blog) <<a href="http://LegalizeAdulthood.wordpress.com" rel="noreferrer" target="_blank" class="cremed">http://LegalizeAdulthood.wordpress.com</a>><br>
_______________________________________________<br>
cfe-dev mailing list<br>
<a href="mailto:cfe-dev@lists.llvm.org" target="_blank" class="cremed">cfe-dev@lists.llvm.org</a><br>
<a href="http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev" rel="noreferrer" target="_blank" class="cremed">http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev</a><br>
</div></div></blockquote></div><br></div></div></div>
_______________________________________________<br>
cfe-dev mailing list<br>
<a href="mailto:cfe-dev@lists.llvm.org" target="_blank" class="cremed">cfe-dev@lists.llvm.org</a><br>
<a href="http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev" rel="noreferrer" target="_blank" class="cremed">http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev</a><br>
</blockquote></div></div></div></div>
</blockquote></div><br></div></div>