<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;" class="">Thanks for pointing me towards those docs, they seem like excellent candidates for linking from diagnostics! Providing more information when encountering errors related to things like attributes and command line args that users may not encounter on a regular basis is exactly in line with my goals when adding this.<div class=""><br class=""></div><div class="">It seems apparent that I probably shouldn’t assume documentation will be installed locally when generalizing this feature to work with Clang. Swift ships the docs alongside the compiler primarily because the language and diagnostics are still evolving rapidly, and we don’t have a good mechanism to host versioned documentation at the moment. On the other hand, linking to something like <a href="https://clang.llvm.org/docs/LanguageExtensions.html#non-standard-c-11-attributes" class="">https://clang.llvm.org/docs/LanguageExtensions.html#non-standard-c-11-attributes</a> from Clang diagnostics seems perfectly sensible, and there’s no reason I can think of not to support both web and file URLs.</div><div class=""><br class=""></div><div class="">I’ll look into Clang’s diagnostics infrastructure to get a better idea of how documentation links can be integrated throughout before moving ahead with the serialization format updates. I think my originally proposed changes are still a little too Swift-specific.</div><div class=""><br class=""></div><div class="">— Owen</div><div class=""><div><br class=""><blockquote type="cite" class=""><div class="">On May 19, 2020, at 7:49 AM, Finkel, Hal J. <<a href="mailto:hfinkel@anl.gov" class="">hfinkel@anl.gov</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><blockquote style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; text-decoration: none; border-left-width: 3px; border-left-style: solid; border-color: rgb(200, 200, 200); padding-left: 1ex; margin-left: 0.8ex; color: rgb(102, 102, 102);" class=""><div class=""><br class="Apple-interchange-newline"><hr tabindex="-1" style="display: inline-block; width: 1361.921875px;" class=""><div id="divRplyFwdMsg" dir="ltr" class=""><font face="Calibri, sans-serif" style="font-size: 11pt;" class=""><b class="">From:</b><span class="Apple-converted-space"> </span>Aaron Ballman <<a href="mailto:aaron.ballman@gmail.com" class="">aaron.ballman@gmail.com</a>><br class=""><b class="">Sent:</b><span class="Apple-converted-space"> </span>Tuesday, May 19, 2020 7:44 AM<br class=""><b class="">To:</b><span class="Apple-converted-space"> </span>Finkel, Hal J. <<a href="mailto:hfinkel@anl.gov" class="">hfinkel@anl.gov</a>><br class=""><b class="">Cc:</b><span class="Apple-converted-space"> </span><a href="mailto:cfe-dev@lists.llvm.org" class="">cfe-dev@lists.llvm.org</a> <<a href="mailto:cfe-dev@lists.llvm.org" class="">cfe-dev@lists.llvm.org</a>>; Owen Voorhees <<a href="mailto:owenvoorhees@gmail.com" class="">owenvoorhees@gmail.com</a>><br class=""><b class="">Subject:</b><span class="Apple-converted-space"> </span>Re: [cfe-dev] [RFC] Upstreaming proposed change to .dia format from Swift</font><div class=""> </div></div><div class="BodyFragment"><font size="2" class=""><span style="font-size: 11pt;" class=""><div class="PlainText">On Tue, May 19, 2020 at 6:26 AM Finkel, Hal J. <<a href="mailto:hfinkel@anl.gov" class="">hfinkel@anl.gov</a>> wrote:<br class="">><br class="">> Hi, Owen,<br class="">><br class="">> I think having documentation links associated with diagnostics is a useful feature, and I would be happy to see it in Clang.<br class=""><br class="">I agree, I think this is a great idea! Hopefully we can also make use<br class="">of it (or something like it) in clang-tidy as well.<br class=""><br class="">> I would encourage the addition of appropriate links to Clang's<span class="Apple-converted-space"> </span><a href="https://clang.llvm.org/docs/LanguageExtensions.html" class="">https://clang.llvm.org/docs/LanguageExtensions.html</a><span class="Apple-converted-space"> </span>and, moreover, maybe we can generate these for mis-applied attributes in some automated way (given that our attribute docs are also TableGen-generated).<br class=""><br class="">Are you envisioning something like `[[gnu::nonnull]] int *i;` giving<br class="">you a diagnostic about the attribute being ignored because it doesn't<br class="">apply to local variables, along with a link directly to the<br class="">documentation for that attribute? If so, that's a neat idea! We could<br class="">possibly even do something like that for unknown or misspelled command<br class="">line arguments, because the command line reference is also table<br class=""></div><div class="PlainText">generated.<br class=""></div></span></font></div></div></blockquote><div class="PlainText" style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;"><br class=""></div><div class="PlainText" style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;"><br class=""></div><div class="PlainText" style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;">Yes, exactly. I'm glad that you agree<span class="Apple-converted-space"> </span><span id="🙂" class="">🙂</span></div><div class="PlainText" style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;"><span class=""><br class=""></span></div><div class="PlainText" style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;"><span class=""> -Hal</span></div><div class="PlainText" style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;"><br class=""></div><blockquote style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; text-decoration: none; border-left-width: 3px; border-left-style: solid; border-color: rgb(200, 200, 200); padding-left: 1ex; margin-left: 0.8ex; color: rgb(102, 102, 102);" class=""><div class=""><div class="BodyFragment"><font size="2" class=""><span style="font-size: 11pt;" class=""><div class="PlainText"><br class="">~Aaron<br class=""><br class="">><br class="">> -Hal<br class="">><br class="">> Hal Finkel<br class="">> Lead, Compiler Technology and Programming Languages<br class="">> Leadership Computing Facility<br class="">> Argonne National Laboratory<br class="">><br class="">> ________________________________<br class="">> From: cfe-dev <<a href="mailto:cfe-dev-bounces@lists.llvm.org" class="">cfe-dev-bounces@lists.llvm.org</a>> on behalf of Owen Voorhees via cfe-dev <<a href="mailto:cfe-dev@lists.llvm.org" class="">cfe-dev@lists.llvm.org</a>><br class="">> Sent: Monday, May 18, 2020 10:15 AM<br class="">> To: <a href="mailto:cfe-dev@lists.llvm.org" class="">cfe-dev@lists.llvm.org</a> <<a href="mailto:cfe-dev@lists.llvm.org" class="">cfe-dev@lists.llvm.org</a>><br class="">> Subject: [cfe-dev] [RFC] Upstreaming proposed change to .dia format from Swift<br class="">><br class="">> Hi all,<br class="">><br class="">> I was hoping to get some feedback on a proposed change to clang's serialized diagnostics format.<br class="">><br class="">> To give some background, Swift (<a href="http://swift.org" class="">swift.org</a>) also uses this format for its diagnostics, and we recently added a new feature called "educational notes" which we'd like to start serializing. An educational note is attached to a diagnostic and is essentially just a path to associated documentation somewhere in a compiler toolchain. The documentation can then be displayed alongside emitted diagnostics to teach users about relevant language concepts or describe common problems and solutions. More details can be found at<span class="Apple-converted-space"> </span><a href="https://github.com/apple/swift/blob/master/docs/Diagnostics.md#educational-notes" class="">https://github.com/apple/swift/blob/master/docs/Diagnostics.md#educational-notes</a><span class="Apple-converted-space"> </span>and an example is available at<span class="Apple-converted-space"> </span><a href="https://github.com/apple/swift/blob/master/userdocs/diagnostics/temporary-pointers.md" class="">https://github.com/apple/swift/blob/master/userdocs/diagnostics/temporary-pointers.md</a>.<br class="">><br class="">> In order to support this use case, I'd like to propose adding new records to the .dia format for educational note paths, or perhaps more generally, documentation paths. The new records would be emitted alongside the main diagnostic record, similar to the handling of ranges and fix-its. I've submitted a patch with the proposed changes here:<span class="Apple-converted-space"> </span><a href="https://reviews.llvm.org/D80126" class="">https://reviews.llvm.org/D80126</a><span class="Apple-converted-space"> </span>.<br class="">><br class="">> The main reason we'd like to upstream this change to Clang instead of just implementing it in Swift is to avoid diverging from the established format. However, it isn't language specific and in the long term I think this is a feature that could benefit Clang's diagnostics quite a bit as well.<br class="">><br class="">> My questions are:<br class="">><br class="">> Is the clang community open to making a change like this that primarily benefits a downstream project (swift) in the short term?<br class="">> Is this a feature clang might be interested in adopting at some point?<br class="">><br class="">><br class="">> Any and all feedback is welcome! Sorry if this is the wrong place to discuss this sort of thing — it's my first time posting to the LLVM lists.<br class="">><br class="">> Thanks,<br class="">> Owen</div></span></font></div></div></blockquote></div></blockquote></div><br class=""></div></body></html>