ApiAnnotations comments are not machine checked

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.

Trac metadata

Trac field	Value
Version	8.1
Type	Bug
TypeOfFailure	OtherFailure
Priority	normal
Resolution	Unresolved
Component	Compiler (Parser)
Test case
Differential revisions
BlockedBy
Related
Blocking
CC
Operating system
Architecture