[GHC] #8944: Warn instead of stopping on misplaced Haddock comments

[GHC]

#8944: Warn instead of stopping on misplaced Haddock comments
-------------------------------------+-------------------------------------
              Reporter:  Fuuzetsu    |            Owner:
                  Type:  feature     |           Status:  new
  request                            |        Milestone:
              Priority:  normal      |          Version:  7.9
             Component:  Compiler    |         Keywords:
  (Parser)                           |     Architecture:  Unknown/Multiple
            Resolution:              |       Difficulty:  Unknown
      Operating System:              |       Blocked By:
  Unknown/Multiple                   |  Related Tickets:
       Type of failure:              |
  None/Unknown                       |
             Test Case:              |
              Blocking:              |
Differential Revisions:  Phab:D452   |
-------------------------------------+-------------------------------------

Comment (by rodlogic):

 Replying to [comment:2 rodlogic]:
 > I have a fix for this in https://phabricator.haskell.org/D452. However,
 I just realized that I forgot to create a specific option for this
 warning. But does this even need an option??

 I did spend some time trying to make the following case work, which is a
 similar to the one described in the summary:
 {{{
 import Data.Maybe
 -- * whatever
 import Data.Functor
 }}}

 Parsing the above with the haddock flag turned on will lead to the
 following error:
 {{{
 a1.hs:3:1: parse error on input ‘import’
 }}}

 When the haddock flag is turned on, the comment line is scanned as a
 ITdocSection token instead of a ITlineComment. However, instead of being
 ignored by the lexer an ITdocSection is returned to the parser as a token.
 The problem is that the import rules are not expecting any documentation
 tokens and the parsing fails.

 So fixing this requires modifying the {{{import}}} rule to be similar to
 how the {{{expor}}}t rules are implemented, i.e. explicitly taking into
 account the different haddock tokens.

 I just find it a bit strange that both the parser and lexer need to know
 about haddock comments. Any changes to haddock (e.g. introducing a new
 haddock comment type) would require changing the GHC's lexer and the
 parser! I was expecting to see the lexer to generate a generic single or
 multiline comment token that would be incorporated into the AST by the
 parser, and then haddock would be able to further process these comments
 based on it's own rules.

 Later this week I will see if I can address the summary case since it may
 be simpler, but it seems that it would be a good idea to generalize the
 parsing of comments and make GHC's parser/lexer a bit more independent of
 Haddock (in a different ticket). Alanz changes to the AST may be a good
 first step here and I will take a closer look there too.

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