<div dir="ltr"><br><br><div class="gmail_quote"><div dir="ltr">On Wed, Oct 7, 2015 at 10:42 PM Daniel Jasper <<a href="mailto:djasper@google.com">djasper@google.com</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 class="gmail_extra"><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">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><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">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></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>Then I don't understand your requirements:</div><div>1. We cannot guarantee that external docs are static.</div></div></div></div></blockquote><div><br></div><div>We can if they are on github through the use of a git hash.</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_extra"><div class="gmail_quote"><div>2. For ToT, we cannot control how external docs are changed.</div></div></div></div></blockquote><div><br></div><div>I think if we do (1), we can.</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_extra"><div class="gmail_quote"><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></div></blockquote><div><br></div><div>Whether we always want to do that is one question I'd like to discuss.</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_extra"><div class="gmail_quote"><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><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">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">CAAt6xTvNGQNBYNj8i0T-jgk3urwuUtjFt6gbbT-tDRdnFm2Uiw@mail.gmail.com</a>>,<br>
<span>    Aaron Ballman via cfe-dev <<a href="mailto:cfe-dev@lists.llvm.org" target="_blank">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">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">http://tinyurl.com/d3d-pipeline</a>><br>
     The Computer Graphics Museum <<a href="http://ComputerGraphicsMuseum.org" rel="noreferrer" target="_blank">http://ComputerGraphicsMuseum.org</a>><br>
         The Terminals Wiki <<a href="http://terminals.classiccmp.org" rel="noreferrer" target="_blank">http://terminals.classiccmp.org</a>><br>
  Legalize Adulthood! (my blog) <<a href="http://LegalizeAdulthood.wordpress.com" rel="noreferrer" target="_blank">http://LegalizeAdulthood.wordpress.com</a>><br>
_______________________________________________<br>
cfe-dev mailing list<br>
<a href="mailto:cfe-dev@lists.llvm.org" target="_blank">cfe-dev@lists.llvm.org</a><br>
<a href="http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev" rel="noreferrer" target="_blank">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">cfe-dev@lists.llvm.org</a><br>
<a href="http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev" rel="noreferrer" target="_blank">http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev</a><br>
</blockquote></div></div></div></div>
</blockquote></div></div></div></blockquote></div></div>