My goal is to make Parser.y simpler.

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. Also, it is conceivable we could move the logic of associating comments with AST nodes from GHC to Haddock itself.