[haddock] #94: Give a warning message instead of an error when encountering unexpected Haddock comments

[haddock]

#94: Give a warning message instead of an error when encountering unexpected
Haddock comments
------------------------+---------------------------------------------------
Reporter:  waern        |        Owner:     
    Type:  enhancement  |       Status:  new
Priority:  major        |    Milestone:  _|_
 Version:               |   Resolution:     
Keywords:               |  
------------------------+---------------------------------------------------
Old description:

> See this failure when processing XMonad:
> {{{
> XMonad/Layout.hs:55:19: parse error on input `!' haddock: Failed to check
> module: XMonad.Layout
>
> The relevant lines:
>
> data Tall a = Tall !Int -- ^ The default number of windows in the master
> pane (default: 1)
>                    !Rational -- ^ Default proportion of screen occupied
> by master pane (default: 1/2)
>                    !Rational; -- ^ Percent of screen to increment by when
> resizing panes (default: 3/100)
> }}}
>
> Since we don't support Haddock comments on individual arguments of
> constructors, this just fails with a parse error. Perhaps we should just
> give a warning in case like this, where a Haddock comment is encountered
> at an unexpected place.
>
> I think this is hard to implement, given the way things currently work.
> Haddock comments are just ordinary tokens that are fed to the parser, and
> we clearly don't want put them all over the grammar. If we should move to
> a design where Haddock comments are not in the grammar, but are collected
> elsewhere, implement this ticket would be a lot easier.

New description:

 See this failure when processing XMonad:
 {{{
 XMonad/Layout.hs:55:19: parse error on input `!' haddock: Failed to check
 module: XMonad.Layout

 The relevant lines:

 data Tall a = Tall !Int -- ^ The default number of windows in the master
 pane (default: 1)
                    !Rational -- ^ Default proportion of screen occupied by
 master pane (default: 1/2)
                    !Rational; -- ^ Percent of screen to increment by when
 resizing panes (default: 3/100)
 }}}

 Since we don't support Haddock comments on individual arguments of
 constructors, this just fails with a parse error. Perhaps we should give a
 warning message instead. In general, it would be good if we give a warning
 message instead of a parse error whenever a Haddock comment is encountered
 where it is not expected.

 I think implementing this is hard, given the way things currently work.
 Haddock comments are just ordinary tokens that are fed to the parser in
 GHC, and we clearly don't want put them all over the grammar. If we should
 move to a design where Haddock comments are not in the grammar, but are
 collected elsewhere, implementing this ticket would be easier.

-- 
Ticket URL: <http://trac.haskell.org/haddock/ticket/94#comment:3>
haddock <http://www.haskell.org/haddock>
Haddock, The Haskell Documentation Tool