[GHC] #8663: Fix up Haddock mark-up

[GHC]

#8663: Fix up Haddock mark-up
------------------------------------+--------------------------------------
       Reporter:  Fuuzetsu          |             Owner:
           Type:  task              |            Status:  new
       Priority:  normal            |         Milestone:
      Component:  Compiler          |           Version:  7.7
       Keywords:                    |  Operating System:  Unknown/Multiple
   Architecture:  Unknown/Multiple  |   Type of failure:  Documentation bug
     Difficulty:  Unknown           |         Test Case:
     Blocked By:                    |          Blocking:
Related Tickets:                    |
------------------------------------+--------------------------------------
 New Haddock changes will mean that any previously failing Haddock parses
 (which resulted in no documentation) will now be parsed. This means that
 the resulting documentation might not look too great. These need to be
 human-checked and fixed up if needed.

 Here are the failures from recent validate run:
 {{{
 14923:doc comment parse failed:  block decorated with fact
 14924- @ end dg.tex
 14925-Warning: Compiler.Hoopl.Dataflow: Instances of type and data
 families and equations of closed type families are not yet
 supported.Instances of the following families will be filtered out:
 14926-  Fact
 14927-  30% ( 10 / 33) in 'Compiler.Hoopl.Dataflow'
 }}}

 {{{
 17735:doc comment parse failed:  plusUFM_CD  f m1 d1 m2 d2
 17736-   merges the maps using `f` as the combinding function and d1 resp.
 d2 as
 17737-   the default value if there is no entry in m1 reps. m2. The domain
 is the union
 17738-   of the domains of m1 m2.
 17739-   Representative example:
 17740-   > plusUFM_CD f {A: 1, B: 2} 23 {B: 3, C: 4} 42
 17741-   >   == {A: f 1 42, B: f 2 3, C: f 23 4 }
 17742-   4% (  2 / 49) in 'UniqFM'
 }}}

 {{{
 17790:doc comment parse failed:  If @co :: T ts ~ rep_ty@ then:
 17791-
 17792- > instNewTyCon_maybe T ts = Just (rep_ty, co)
 17793- Checks for a newtype, and for being saturated
 17794-  32% ( 38 /117) in 'Coercion'
 }}}

 {{{
 17813-haddock module header parse failed: Cannot parse header
 documentation paragraphs
 17814-  75% (  3 /  4) in 'Llvm.MetaData'
 }}}

 {{{
 18100:doc comment parse failed:  @argTyFold@ implements a generalised and
 safer variant of the @arg@
 18101- function from Figure 3 in
 <http://dreixel.net/research/pdf/gdmh.pdf>. @arg@
 18102- is conceptually equivalent to:
 18103-
 18104- > arg t = case t of
 18105- >   _ | isTyVar t         -> if (t == argVar) then Par1 else Par0 t
 18106- >   App f [t'] |
 18107-       representable1 f &&
 18108-       t' == argVar        -> Rec1 f
 18109- >   App f [t'] |
 18110-       representable1 f &&
 18111-       t' has tyvars       -> f :.: (arg t')
 18112- >   _                     -> Rec0 t
 18113-
 18114- where @argVar@ is the last type variable in the data type
 declaration we are
 18115- finding the representation for.
 18116-
 18117- @argTyFold@ is more general than @arg@ because it uses 'ArgTyAlg'
 to
 18118- abstract out the concrete invocations of @Par0@, @Rec0@, @Par1@,
 @Rec1@, and
 18119- @:.:@.
 18120-
 18121- @argTyFold@ is safer than @arg@ because @arg@ would lead to a GHC
 panic for
 18122- some data types. The problematic case is when @t@ is an application
 of a
 18123- non-representable type @f@ to @argVar@: @App f [argVar]@ is caught
 by the
 18124- @_@ pattern, and ends up represented as @Rec0 t at . This type occurs
 /free/ in
 18125- the RHS of the eventual @Rep1@ instance, which is therefore ill-
 formed. Some
 18126- representable1 checks have been relaxed, and others were moved to
 18127- @canDoGenerics1 at .
 18128-   0% (  0 /  8) in 'TcGenGenerics'
 }}}

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