Review for !2377 Haddock and GHC

[Simon Peyton Jones]

Fellow GHC devs
I'd like to ask your help with reviewing a GHC patch
!2377: Accumulate Haddock comments in P (#17544, #17561, #8944)<https://gitlab.haskell.org/ghc/ghc/-/merge_requests/2377/diffs#diff-content-13755bdc5d6c6b4c6f31604eb0da778521355795>

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.

But it's had surprisingly little review, especially for a patch that potentially affects quite a lot of people (incl Haddock folk, IDE folk).

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.

We'll land it regardless in a couple of weeks.

Thanks!

Simon

Summary of the payload (taken from #17544)

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 HsDocTy and the like (and if it does, that's a bug).
Here's the design I propose instead:

  1.  Accumulate Haddock comments with their locations in the P monad. This logic will be very easy to add in the lexer.
  2.  After parsing, do a pass over the AST to associate Haddock comments with AST nodes using location info.
  3.  Report the leftover comments to the user as a warning or an error.
This means

  *   The happy grammar won't even have the notion of a Haddock comment.
  *   Parser.y becomes quite a bit simpler.
  *   Ultimately, it is conceivable we could move the logic of associating Haddock comments with AST nodes from GHC to Haddock itself
A detailed overview of the implementation plan is in comments at the start of compiler/GHC/Parser/PostProcess/Haddock.hs<https://gitlab.haskell.org/ghc/ghc/-/merge_requests/2377/diffs#diff-content-13755bdc5d6c6b4c6f31604eb0da778521355795>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20200715/d4c6593e/attachment.html>