<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:Wingdings;
panose-1:5 0 0 0 0 0 0 0 0 0;}
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin-top:6.0pt;
margin-right:0cm;
margin-bottom:6.0pt;
margin-left:0cm;
font-size:11.0pt;
font-family:"Calibri",sans-serif;
mso-fareast-language:EN-US;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:#0563C1;
text-decoration:underline;}
p.MsoListParagraph, li.MsoListParagraph, div.MsoListParagraph
{mso-style-priority:34;
margin-top:6.0pt;
margin-right:0cm;
margin-bottom:6.0pt;
margin-left:36.0pt;
font-size:11.0pt;
font-family:"Calibri",sans-serif;
mso-fareast-language:EN-US;}
span.EmailStyle18
{mso-style-type:personal-compose;
font-family:"Calibri",sans-serif;
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;
font-family:"Calibri",sans-serif;
mso-fareast-language:EN-US;}
.MsoPapDefault
{mso-style-type:export-only;
margin-top:6.0pt;
margin-right:0cm;
margin-bottom:6.0pt;
margin-left:0cm;}
@page WordSection1
{size:612.0pt 792.0pt;
margin:72.0pt 72.0pt 72.0pt 72.0pt;}
div.WordSection1
{page:WordSection1;}
/* List Definitions */
@list l0
{mso-list-id:1255044052;
mso-list-template-ids:-1052456792;}
@list l1
{mso-list-id:1519924052;
mso-list-type:hybrid;
mso-list-template-ids:-1867894544 134807553 134807555 134807557 134807553 134807555 134807557 134807553 134807555 134807557;}
@list l1:level1
{mso-level-number-format:bullet;
mso-level-text:\F0B7;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-18.0pt;
font-family:Symbol;}
@list l1:level2
{mso-level-number-format:bullet;
mso-level-text:o;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-18.0pt;
font-family:"Courier New";}
@list l1:level3
{mso-level-number-format:bullet;
mso-level-text:\F0A7;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-18.0pt;
font-family:Wingdings;}
@list l1:level4
{mso-level-number-format:bullet;
mso-level-text:\F0B7;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-18.0pt;
font-family:Symbol;}
@list l1:level5
{mso-level-number-format:bullet;
mso-level-text:o;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-18.0pt;
font-family:"Courier New";}
@list l1:level6
{mso-level-number-format:bullet;
mso-level-text:\F0A7;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-18.0pt;
font-family:Wingdings;}
@list l1:level7
{mso-level-number-format:bullet;
mso-level-text:\F0B7;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-18.0pt;
font-family:Symbol;}
@list l1:level8
{mso-level-number-format:bullet;
mso-level-text:o;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-18.0pt;
font-family:"Courier New";}
@list l1:level9
{mso-level-number-format:bullet;
mso-level-text:\F0A7;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-18.0pt;
font-family:Wingdings;}
ol
{margin-bottom:0cm;}
ul
{margin-bottom:0cm;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</head>
<body lang="EN-GB" link="#0563C1" vlink="#954F72">
<div class="WordSection1">
<p class="MsoNormal">Fellow GHC devs<o:p></o:p></p>
<p class="MsoNormal">I’d like to ask your help with reviewing a GHC patch<o:p></o:p></p>
<p class="MsoNormal" style="margin-left:36.0pt"><a href="https://gitlab.haskell.org/ghc/ghc/-/merge_requests/2377/diffs#diff-content-13755bdc5d6c6b4c6f31604eb0da778521355795" target="_blank"><b><span style="font-size:11.5pt;font-family:"Arial",sans-serif;background:#F8F8F8;text-decoration:none">!2377:
Accumulate Haddock comments in P (#17544, #17561, #8944)</span></b></a><o:p></o:p></p>
<p>It’s a substantial patch to the parser, changing the way in which Haddock documentation is parsed. It moves us in a good direction; it makes us more robust for the future; Vlad has invested a lot of effort in it; and I’m sure we should land it.<o:p></o:p></p>
<p>But it’s had surprisingly little review, especially for a patch that potentially affects quite a lot of people (incl Haddock folk, IDE folk).<o:p></o:p></p>
<p>So, would any of you be willing to review the code itself? Especially folk involved in Haddock or Haskell IDE. Early versions were not easy to understand, but Vlad has invested a lot of effort in both simplifying it and in documenting it.<o:p></o:p></p>
<p>We’ll land it regardless in a couple of weeks.<o:p></o:p></p>
<p>Thanks!<o:p></o:p></p>
<p>Simon<o:p></o:p></p>
<p><b>Summary of the payload (taken from #17544)<o:p></o:p></b></p>
<p>Currently Haddock comments are, first and foremost, comments. It's very annoying to incorporate them into the grammar. We can take advantage of an important property: adding a Haddock comment does not change the parse tree in any way other than wrapping
some nodes in <span style="font-size:10.0pt;font-family:"Courier New"">HsDocTy</span> and the like (and if it does, that's a bug).<o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="mso-fareast-language:EN-GB">Here's the design I propose instead:<o:p></o:p></span></p>
<ol start="1" type="1">
<li class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;mso-list:l0 level1 lfo1">
<span style="mso-fareast-language:EN-GB">Accumulate Haddock comments with their locations in the
</span><span style="font-size:10.0pt;font-family:"Courier New";mso-fareast-language:EN-GB">P</span><span style="mso-fareast-language:EN-GB"> monad. This logic will be very easy to add in the lexer.<o:p></o:p></span></li><li class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;mso-list:l0 level1 lfo1">
<span style="mso-fareast-language:EN-GB">After parsing, do a pass over the AST to associate Haddock comments with AST nodes using location info.<o:p></o:p></span></li><li class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;mso-list:l0 level1 lfo1">
<span style="mso-fareast-language:EN-GB">Report the leftover comments to the user as a warning or an error.<o:p></o:p></span></li></ol>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="mso-fareast-language:EN-GB">This means
<o:p></o:p></span></p>
<ul type="disc">
<li class="MsoListParagraph" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:0cm;mso-list:l1 level1 lfo2">
<span style="mso-fareast-language:EN-GB">The </span><span style="font-size:10.0pt;font-family:"Courier New";mso-fareast-language:EN-GB">happy</span><span style="mso-fareast-language:EN-GB"> grammar won't even have the notion of a Haddock comment.
<o:p></o:p></span></li><li class="MsoListParagraph" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:0cm;mso-list:l1 level1 lfo2">
<span style="mso-fareast-language:EN-GB">Parser.y becomes quite a bit simpler. <o:p></o:p></span></li><li class="MsoListParagraph" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:0cm;mso-list:l1 level1 lfo2">
Ultimately, it is conceivable we could move the logic of associating Haddock comments with AST nodes from GHC to Haddock itself<span style="mso-fareast-language:EN-GB"><o:p></o:p></span></li></ul>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="mso-fareast-language:EN-GB">A detailed overview of the implementation plan is in comments at the start of
</span><b><span style="font-size:11.5pt;font-family:"Arial",sans-serif;color:#1D1C1D;background:#F8F8F8"><a href="https://gitlab.haskell.org/ghc/ghc/-/merge_requests/2377/diffs#diff-content-13755bdc5d6c6b4c6f31604eb0da778521355795" target="_blank">compiler/GHC/Parser/PostProcess/Haddock.hs</a></span></b><span style="mso-fareast-language:EN-GB"><o:p></o:p></span></p>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
</body>
</html>