[GHC] #13012: ApiAnnotations comments are not machine checked

[GHC]

#13012: ApiAnnotations comments are not machine checked
-------------------------------------+-------------------------------------
           Reporter:  ezyang         |             Owner:  alanz
               Type:  bug            |            Status:  new
           Priority:  normal         |         Milestone:
          Component:  Compiler       |           Version:  8.1
  (Parser)                           |
           Keywords:                 |  Operating System:  Unknown/Multiple
       Architecture:                 |   Type of failure:  None/Unknown
  Unknown/Multiple                   |
          Test Case:                 |        Blocked By:
           Blocking:                 |   Related Tickets:
Differential Rev(s):                 |         Wiki Page:
-------------------------------------+-------------------------------------
 Sprinkled throughout the codebase are comments like this:

 {{{
   -- | let(rec)
   --
   -- - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnLet',
   --       'ApiAnnotation.AnnOpen' @'{'@,
   --       'ApiAnnotation.AnnClose' @'}'@,'ApiAnnotation.AnnIn'
 }}}

 The comments are intended to describe the set of annotations that might be
 possibly associated with an AST node of this constructor.

 However, the source of truth about these comments is the Parser itself.
 It's not difficult to imagine that these comments might get out of date if
 changes are made to the Parser. Nor does the comment in `ApiAnnotations`
 nor the wiki page (https://ghc.haskell.org/trac/ghc/wiki/ApiAnnotations)
 explain what the comments are for, and I only recently figured out what
 they actually mean. (I'm working on a doc patch to improve this.)

 Ideally, the set of permissible annotations would be encoded in *machine-
 readable* form, as a contract that we can use to check that the parser
 upholds the contract. Here is my suggestion: we create a function to
 recursively traverse a parsed module, and verify that the only annotations
 associated with any given SrcSpan are the "valid" ones for that AST
 element. We can enable this extra pass as an "annotation lint" and turn it
 on for all tests in the test suite.

--
Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/13012>
GHC <http://www.haskell.org/ghc/>
The Glasgow Haskell Compiler