<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=Windows-1252">
<style type="text/css" style="display:none;"> P {margin-top:0;margin-bottom:0;} </style>
</head>
<body dir="ltr">
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
Hi, Owen,</div>
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
I think having documentation links associated with diagnostics is a useful feature, and I would be happy to see it in Clang.</div>
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
I would encourage the addition of appropriate links to Clang's <a href="https://clang.llvm.org/docs/LanguageExtensions.html" id="LPNoLP411576">https://clang.llvm.org/docs/LanguageExtensions.html</a> and, moreover, maybe we can generate these for mis-applied
attributes in some automated way (given that our attribute docs are also TableGen-generated).</div>
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
-Hal</div>
<div>
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<div id="Signature">
<div class="BodyFragment"><font size="2"><span style="font-size:10pt;">
<div class="PlainText">Hal Finkel<br>
Lead, Compiler Technology and Programming Languages<br>
Leadership Computing Facility<br>
Argonne National Laboratory</div>
</span></font></div>
</div>
</div>
<div>
<div id="appendonsend"></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:12pt; color:rgb(0,0,0)">
<br>
</div>
<hr tabindex="-1" style="display:inline-block; width:98%">
<div id="divRplyFwdMsg" dir="ltr"><font face="Calibri, sans-serif" color="#000000" style="font-size:11pt"><b>From:</b> cfe-dev <cfe-dev-bounces@lists.llvm.org> on behalf of Owen Voorhees via cfe-dev <cfe-dev@lists.llvm.org><br>
<b>Sent:</b> Monday, May 18, 2020 10:15 AM<br>
<b>To:</b> cfe-dev@lists.llvm.org <cfe-dev@lists.llvm.org><br>
<b>Subject:</b> [cfe-dev] [RFC] Upstreaming proposed change to .dia format from Swift</font>
<div> </div>
</div>
<div class="" style="word-wrap:break-word; line-break:after-white-space">
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"">
Hi all,</div>
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"; min-height:14px">
<br class="">
</div>
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"">
I was hoping to get some feedback on a proposed change to clang's serialized diagnostics format.</div>
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"; min-height:14px">
<br class="">
</div>
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"">
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 <a href="https://github.com/apple/swift/blob/master/docs/Diagnostics.md#educational-notes" class="">
<span class="" style="color:#dca10d">https://github.com/apple/swift/blob/master/docs/Diagnostics.md#educational-notes</span></a> and an example is available at
<a href="https://github.com/apple/swift/blob/master/userdocs/diagnostics/temporary-pointers.md" class="">
<span class="" style="color:#dca10d">https://github.com/apple/swift/blob/master/userdocs/diagnostics/temporary-pointers.md</span></a>. </div>
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"; min-height:14px">
<br class="">
</div>
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"">
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: <a href="https://reviews.llvm.org/D80126" class="">
<span class="" style="color:#dca10d">https://reviews.llvm.org/D80126</span></a> .</div>
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"; min-height:14px">
<br class="">
</div>
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"">
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.</div>
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"; min-height:14px">
<br class="">
</div>
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"">
My questions are:</div>
<ul class="">
<li class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"">
Is the clang community open to making a change like this that primarily benefits a downstream project (swift) in the short term?</li><li class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"">
Is this a feature clang might be interested in adopting at some point? </li></ul>
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"; min-height:14px">
<br class="">
</div>
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"">
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.</div>
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"; min-height:14px">
<br class="">
</div>
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"">
Thanks,</div>
<div class="" style="margin:0px; font-stretch:normal; line-height:normal; font-family:"Helvetica Neue"">
Owen</div>
</div>
</div>
</body>
</html>