Ticket #5469: 0001-Add-more-documentation.patch

File 0001-Add-more-documentation.patch, 21.0 KB (added by reinerp, 3 years ago)
  • Language/Haskell/TH/Syntax.hs

    From 9f952f35a773a477d924f0f6694224474b9e7062 Mon Sep 17 00:00:00 2001
    From: Reiner Pope <[email protected]>
    Date: Sat, 9 Jun 2012 15:32:30 +1000
    Subject: [PATCH 1/4] Add more documentation.
    
    ---
     Language/Haskell/TH/Syntax.hs |  410 +++++++++++++++++++++++++++++++++--------
     1 files changed, 330 insertions(+), 80 deletions(-)
    
    diff --git a/Language/Haskell/TH/Syntax.hs b/Language/Haskell/TH/Syntax.hs
    index c18d801..e7a72a8 100644
    a b counter = unsafePerformIO (newIORef 0) 
    147147
    148148newtype Q a = Q { unQ :: forall m. Quasi m => m a }
    149149
     150-- \"Runs\" the 'Q' monad. Normal users of Template Haskell
     151-- should not need this function, as the splice brackets @$( ... )@
     152-- are the usual way of running a 'Q' computation.
     153--
     154-- This function is primarily used in GHC internals, and for debugging
     155-- splices by running them in 'IO'.
     156--
     157-- Note that many functions in 'Q', such as 'reify' and other compiler
     158-- queries, are not supported when running 'Q' in 'IO'; these operations
     159-- simply fail at runtime. Indeed, the only operations guaranteed to succeed
     160-- are 'newName', 'runIO', 'reportError' and 'reportWarning'.
    150161runQ :: Quasi m => Q a -> m a
    151162runQ (Q m) = m
    152163
    instance Applicative Q where 
    165176
    166177----------------------------------------------------
    167178-- Packaged versions for the programmer, hiding the Quasi-ness
     179
     180{- |
     181Generate a fresh name, which cannot be captured.
     182
     183For example, this:
     184
     185@f = $(do
     186  nm1 <- newName \"x\"
     187  let nm2 = 'mkName' \"x\"
     188  return ('LamE' ['VarP' nm1] (LamE [VarP nm2] ('VarE' nm1)))
     189 )@
     190
     191will produce the splice
     192
     193>f = \x0 -> \x -> x0
     194
     195In particular, the occurrence @VarE nm1@ refers to the binding @VarP nm1@,
     196and is not captured by the binding @VarP nm2@.
     197
     198Although names generated by @newName@ cannot /be captured/, they can
     199/capture/ other names. For example, this:
     200
     201>g = $(do
     202>  nm1 <- newName "x"
     203>  let nm2 = mkName "x"
     204>  return (LamE [VarP nm2] (LamE [VarP nm1] (VarE nm2)))
     205> )
     206
     207will produce the splice
     208
     209>g = \x -> \x0 -> x0
     210
     211since the occurrence @VarE nm2@ is captured by the innermost binding
     212of @x@, namely @VarP nm1@.
     213-}
    168214newName :: String -> Q Name
    169215newName s = Q (qNewName s)
    170216
     217-- | Report an error (True) or warning (False),
     218-- but carry on; use 'fail' to stop.
    171219report  :: Bool -> String -> Q ()
    172220report b s = Q (qReport b s)
    173221
    174 recover :: Q a -- ^ recover with this one
    175         -> Q a -- ^ failing action
     222-- | Recover from errors raised by 'reportError' or 'fail'.
     223recover :: Q a -- ^ handler to invoke on failure
     224        -> Q a -- ^ computation to run
    176225        -> Q a
    177226recover (Q r) (Q m) = Q (qRecover r m)
    178227
    recover (Q r) (Q m) = Q (qRecover r m) 
    181230lookupName :: Bool -> String -> Q (Maybe Name)
    182231lookupName ns s = Q (qLookupName ns s)
    183232
    184 lookupTypeName, lookupValueName :: String -> Q (Maybe Name)
     233-- | Look up the given name in the (type namespace of the) current splice's scope. See "Language.Haskell.TH.Syntax#namelookup" for more details.
     234lookupTypeName :: String -> Q (Maybe Name)
    185235lookupTypeName  s = Q (qLookupName True s)
     236
     237-- | Look up the given name in the (value namespace of the) current splice's scope. See "Language.Haskell.TH.Syntax#namelookup" for more details.
     238lookupValueName :: String -> Q (Maybe Name)
    186239lookupValueName s = Q (qLookupName False s)
    187240
    188 -- | 'reify' looks up information about the 'Name'
     241{-
     242Note [Name lookup]
     243~~~~~~~~~~~~~~~~~~
     244-}
     245{- $namelookup #namelookup#
     246The functions 'lookupTypeName' and 'lookupValueName' provide
     247a way to query the current splice's context for what names
     248are in scope. The function 'lookupTypeName' queries the type
     249namespace, whereas 'lookupValueName' queries the value namespace,
     250but the functions are otherwise identical.
     251
     252A call @lookupValueName s@ will check if there is a value
     253with name @s@ in scope at the current splice's location. If
     254there is, the @Name@ of this value is returned;
     255if not, then @Nothing@ is returned.
     256
     257The returned name cannot be \"captured\".
     258For example:
     259
     260> f = "global"
     261> g = $( do
     262>          Just nm <- lookupValueName "f"
     263>          [| let f = "local" in $( varE nm ) |]
     264
     265In this case, @g = \"global\"@; the call to @lookupValueName@
     266returned the global @f@, and this name was /not/ captured by
     267the local definition of @f@.
     268
     269The lookup is performed in the context of the /top-level/ splice
     270being run. For example:
     271
     272> f = "global"
     273> g = $( [| let f = "local" in
     274>            $(do
     275>                Just nm <- lookupValueName "f"
     276>                varE nm
     277>             ) |] )
     278
     279Again in this example, @g = \"global\"@, because the call to
     280@lookupValueName@ queries the context of the outer-most @$(...)@.
     281
     282Operators should be queried without any surrounding parentheses, like so:
     283
     284> lookupValueName "+"
     285
     286Qualified names are also supported, like so:
     287
     288> lookupValueName "Prelude.+"
     289> lookupValueName "Prelude.map"
     290
     291-}
     292
     293
     294{- | 'reify' looks up information about the 'Name'.
     295
     296It is sometimes useful to construct the argument name using 'lookupTypeName' or 'lookupValueName'
     297to ensure that we are reifying from the right namespace. For instance, in this context:
     298
     299> data D = D
     300
     301which @D@ does @reify (mkName \"D\")@ return information about? (Answer: @D@-the-type, but don't rely on it.)
     302To ensure we get information about @D@-the-value, use 'lookupValueName':
     303
     304> do
     305>   Just nm <- lookupValueName "D"
     306>   reify nm
     307
     308and to get information about @D@-the-type, use 'lookupTypeName'.
     309-}
    189310reify :: Name -> Q Info
    190311reify v = Q (qReify v)
    191312
    192 -- | 'classInstances' looks up instaces of a class
    193 reifyInstances :: Name -> [Type] -> Q [Dec]
     313{- | @reifyInstances nm tys@ returns a list of visible instances of @nm tys@. That is,
     314if @nm@ is the name of a type class, then all instances of this class at the types @tys@
     315are returned. Alternatively, if @nm@ is the name of a data family or type family,
     316all instances of this family at the types @tys@ are returned.
     317-}
     318reifyInstances :: Name -> [Type] -> Q [InstanceDec]
    194319reifyInstances cls tys = Q (qReifyInstances cls tys)
    195320
     321-- | Is the list of instances returned by 'reifyInstances' nonempty?
    196322isInstance :: Name -> [Type] -> Q Bool
    197323isInstance nm tys = do { decs <- reifyInstances nm tys
    198324                       ; return (not (null decs)) }
    199325
    200 -- | 'location' gives you the 'Location' at which this
    201 -- computation is spliced.
     326-- | The location at which this computation is spliced.
    202327location :: Q Loc
    203328location = Q qLocation
    204329
    occString (OccName occ) = occ 
    363488-----------------------------------------------------
    364489--               Names
    365490-----------------------------------------------------
    366 
    367 -- |
     491--
    368492-- For "global" names ('NameG') we need a totally unique name,
    369493-- so we must include the name-space of the thing
    370494--
    occString (OccName occ) = occ 
    388512-- The 'map' will be a NameG, and 'x' wil be a NameL
    389513--
    390514-- These Names should never appear in a binding position in a TH syntax tree
     515
     516{- $namecapture #namecapture#
     517Much of 'Name' API is concerned with the problem of /name capture/, which
     518can be seen in the following example.
     519
     520> f expr = [| let x = 0 in $expr |]
     521> ...
     522> g x = $( f [| x |] )
     523> h y = $( f [| y |] )
     524
     525A naive desugaring of this would yield:
     526
     527> g x = let x = 0 in x
     528> h y = let x = 0 in y
     529
     530All of a sudden, @g@ and @h@ have different meanings! In this case,
     531we say that the @x@ in the RHS of @g@ has been /captured/
     532by the binding of @x@ in @f@.
     533
     534What we actually want is for the @x@ in @f@ to be distinct from the
     535@x@ in @g@, so we get the following desugaring:
     536
     537> g x = let x' = 0 in x
     538> h y = let x' = 0 in y
     539
     540which avoids name capture as desired.
     541
     542In the general case, we say that a @Name@ can be captured if
     543the thing it refers to can be changed by adding new declarations.
     544-}
     545
     546{- |
     547An abstract type representing names in the syntax tree.
     548
     549'Name's can be constructed in several ways, which come with different
     550name-capture guarantees (see "Language.Haskell.TH.Syntax#namecapture" for
     551an explanation of name capture):
     552
     553  * the built-in syntax @'f@ and @''T@ can be used to construct names,
     554    The expression @'f@ gives a @Name@ which refers to the value @f@
     555    currently in scope, and @''T@ gives a @Name@ which refers to the
     556    type @T@ currently in scope. These names can never be captured.
     557   
     558  * 'lookupValueName' and 'lookupTypeName' are similar to @'f@ and
     559     @''T@ respectively, but the @Name@s are looked up at the point
     560     where the current splice is being run. These names can never be
     561     captured.
     562
     563  * 'newName' monadically generates a new name, which can never
     564     be captured.
     565     
     566  * 'mkName' generates a capturable name.
     567
     568Names constructed using @newName@ and @mkName@ may be used in bindings
     569(such as @let x = ...@ or @\x -> ...@), but names constructed using
     570@lookupValueName@, @lookupTypeName@, @'f@, @''T@ may not.
     571-}
    391572data Name = Name OccName NameFlavour deriving (Typeable, Data)
    392573
    393574data NameFlavour
    data NameSpace = VarName -- ^ Variables 
    452633
    453634type Uniq = Int
    454635
    455 -- | Base, unqualified name.
     636-- | The name without its module prefix
    456637nameBase :: Name -> String
    457638nameBase (Name occ _) = occString occ
    458639
     640-- | Module prefix of a name, if it exists
    459641nameModule :: Name -> Maybe String
    460642nameModule (Name _ (NameQ m))     = Just (modString m)
    461643nameModule (Name _ (NameG _ _ m)) = Just (modString m)
    462644nameModule _                      = Nothing
    463645
     646{- |
     647Generate a capturable name. Occurrences of such names will be
     648resolved according to the Haskell scoping rules at the occurrence
     649site.
     650
     651For example:
     652
     653> f = [| pi + $(varE (mkName "pi")) |]
     654> ...
     655> g = let pi = 3 in $f
     656
     657In this case, @g@ is desugared to
     658
     659> g = Prelude.pi + 3
     660
     661Note that @mkName@ may be used with qualified names:
     662
     663> mkName "Prelude.pi"
     664
     665See also 'Language.Haskell.TH.Lib.dyn' for a useful combinator. The above example could
     666be rewritten using 'dyn' as
     667
     668> f = [| pi + $(dyn "pi") |]
     669-}
    464670mkName :: String -> Name
    465 -- ^ The string can have a '.', thus "Foo.baz",
     671-- The string can have a '.', thus "Foo.baz",
    466672-- giving a dynamically-bound qualified name,
    467673-- in which case we want to generate a NameQ
    468674--
    instance Show Name where 
    589795  show = showName
    590796
    591797-- Tuple data and type constructors
    592 tupleDataName :: Int -> Name    -- ^ Data constructor
    593 tupleTypeName :: Int -> Name    -- ^ Type constructor
     798-- | Tuple data constructor
     799tupleDataName :: Int -> Name
     800-- | Tuple type constructor
     801tupleTypeName :: Int -> Name
    594802
    595803tupleDataName 0 = mk_tup_name 0 DataName
    596804tupleDataName 1 = error "tupleDataName 1"
    mk_tup_name n_commas space 
    608816    tup_mod = mkModName "GHC.Tuple"
    609817
    610818-- Unboxed tuple data and type constructors
    611 unboxedTupleDataName :: Int -> Name    -- ^ Data constructor
    612 unboxedTupleTypeName :: Int -> Name    -- ^ Type constructor
     819-- | Unboxed tuple data constructor
     820unboxedTupleDataName :: Int -> Name
     821-- | Unboxed tuple type constructor
     822unboxedTupleTypeName :: Int -> Name
    613823
    614824unboxedTupleDataName 0 = error "unboxedTupleDataName 0"
    615825unboxedTupleDataName 1 = error "unboxedTupleDataName 1"
    data Loc 
    639849        , loc_start    :: CharPos
    640850        , loc_end      :: CharPos }
    641851
    642 type CharPos = (Int, Int)       -- Line and character position
     852type CharPos = (Int, Int)       -- ^ Line and character position
    643853
    644854
    645855-----------------------------------------------------
    type CharPos = (Int, Int) -- Line and character position 
    650860
    651861-- | Obtained from 'reify' in the 'Q' Monad.
    652862data Info
    653   = -- | A class is reified to its declaration
    654     --   and a list of its instances
    655     ClassI
    656         Dec             -- Declaration of the class
    657         [InstanceDec]   -- The instances of that class
    658 
     863  =
     864  -- | A class, with a list of its visible instances
     865  ClassI
     866      Dec
     867      [InstanceDec]
     868 
     869  -- | A class method
    659870  | ClassOpI
    660         Name    -- The class op itself
    661         Type    -- Type of the class-op (fully polymoprhic)
    662         Name    -- Name of the parent class
    663         Fixity
    664 
     871       Name
     872       Type
     873       ParentName
     874       Fixity
     875 
     876  -- | A \"plain\" type constructor. \"Fancier\" type constructors are returned using 'PrimTyConI' or 'FamilyI' as appropriate
    665877  | TyConI
    666878        Dec
    667879
    668   | FamilyI     -- Type/data families
     880  -- | A type or data family, with a list of its visible instances
     881  | FamilyI
    669882        Dec
    670883        [InstanceDec]
    671 
    672   | PrimTyConI  -- Ones that can't be expressed with a data type
    673                 -- decl, such as (->), Int#
    674         Name
    675         Int     -- Arity
    676         Bool    -- False => lifted type; True => unlifted
    677 
     884 
     885  -- | A \"primitive\" type constructor, which can't be expressed with a 'Dec'. Examples: @(->)@, @Int#@.
     886  | PrimTyConI
     887       Name
     888       Arity
     889       Unlifted
     890 
     891  -- | A data constructor
    678892  | DataConI
    679         Name    -- The data con itself
    680         Type    -- Type of the constructor (fully polymorphic)
    681         Name    -- Name of the parent TyCon
    682         Fixity
     893       Name
     894       Type
     895       ParentName
     896       Fixity
    683897
     898  {- |
     899  A \"value\" variable (as opposed to a type variable, see 'TyVarI').
     900 
     901  The @Maybe Dec@ field contains @Just@ the declaration which
     902  defined the variable -- including the RHS of the declaration --
     903  or else @Nothing@, in the case where the RHS is unavailable to
     904  the compiler. At present, this value is _always_ @Nothing@:
     905  returning the RHS has not yet been implemented because of
     906  lack of interest.
     907  -}
    684908  | VarI
    685         Name    -- The variable itself
    686         Type
    687         (Maybe Dec)     -- Nothing for lambda-bound variables, and
    688                         -- for anything else TH can't figure out
    689                         -- E.g. [| let x = 1 in $(do { d <- reify 'x; .. }) |]
    690         Fixity
     909       Name
     910       Type
     911       (Maybe Dec)
     912       Fixity
    691913
     914  {- |
     915  A type variable.
     916 
     917  The @Type@ field contains the type which underlies the variable.
     918  At present, this is always @'VarT' theName@, but future changes
     919  may permit refinement of this.
     920  -}
    692921  | TyVarI      -- Scoped type variable
    693922        Name
    694923        Type    -- What it is bound to
    695924  deriving( Show, Data, Typeable )
    696925
    697 -- | 'InstanceDec' desribes a single instance of a class or type function
     926{- |
     927In 'ClassOpI' and 'DataConI', name of the parent class or type
     928-}
     929type ParentName = Name
     930
     931-- | In 'PrimTyConI', arity of the type constructor
     932type Arity = Int
     933
     934-- | In 'PrimTyConI', is the type constructor unlifted?
     935type Unlifted = Bool
     936
     937-- | 'InstanceDec' desribes a single instance of a class or type function.
    698938-- It is just a 'Dec', but guaranteed to be one of the following:
    699 --   InstanceD (with empty [Dec])
    700 --   DataInstD or NewtypeInstD (with empty derived [Name])
    701 --   TySynInstD
     939--
     940--   * 'InstanceD' (with empty @['Dec']@)
     941--
     942--   * 'DataInstD' or 'NewtypeInstD' (with empty derived @['Name']@)
     943--
     944--   * 'TySynInstD'
    702945type InstanceDec = Dec
    703946
    704947data Fixity          = Fixity Int FixityDirection
    data Fixity = Fixity Int FixityDirection 
    706949data FixityDirection = InfixL | InfixR | InfixN
    707950    deriving( Eq, Show, Data, Typeable )
    708951
     952-- | Highest allowed operator precedence for 'Fixity' constructor (answer: 9)
    709953maxPrecedence :: Int
    710954maxPrecedence = (9::Int)
    711955
     956-- | Default fixity: @infixl 9@
    712957defaultFixity :: Fixity
    713958defaultFixity = Fixity maxPrecedence InfixL
    714959
    715960
    716 -----------------------------------------------------
    717 --
    718 --      The main syntax data types
    719 --
    720 -----------------------------------------------------
    721 
    722 {- $infix #infix#
     961{-
    723962Note [Unresolved infix]
    724963~~~~~~~~~~~~~~~~~~~~~~~
    725 
     964-}
     965{- $infix #infix#
    726966When implementing antiquotation for quasiquoters, one often wants
    727967to parse strings into expressions:
    728968
    729 > parse :: String -> Maybe 'Exp'
     969> parse :: String -> Maybe Exp
    730970
    731971But how should we parse @a + b * c@? If we don't know the fixities of
    732972@+@ and @*@, we don't know whether to parse it as @a + (b * c)@ or @(a
    reassociate the tree as necessary. 
    7811021
    7821022-}
    7831023
     1024-----------------------------------------------------
     1025--
     1026--      The main syntax data types
     1027--
     1028-----------------------------------------------------
     1029
    7841030data Lit = CharL Char
    7851031         | StringL String
    7861032         | IntegerL Integer     -- ^ Used for overloaded and non-overloaded
    data Pat 
    8091055  | InfixP Pat Name Pat           -- ^ @foo ({x :+ y}) = e@
    8101056  | UInfixP Pat Name Pat          -- ^ @foo ({x :+ y}) = e@
    8111057                                  --
    812                                   -- See Note [Unresolved infix] at "Language.Haskell.TH.Syntax#infix"
     1058                                  -- See "Language.Haskell.TH.Syntax#infix"
    8131059  | ParensP Pat                   -- ^ @{(p)}@
    8141060                                  --
    815                                   -- See Note [Unresolved infix] at "Language.Haskell.TH.Syntax#infix"
     1061                                  -- See "Language.Haskell.TH.Syntax#infix"
    8161062  | TildeP Pat                    -- ^ @{ ~p }@
    8171063  | BangP Pat                     -- ^ @{ !p }@
    8181064  | AsP Name Pat                  -- ^ @{ x \@ p }@
    data Clause = Clause [Pat] Body [Dec] 
    8311077                                  -- ^ @f { p1 p2 = body where decs }@
    8321078    deriving( Show, Eq, Data, Typeable )
    8331079 
    834 -- | The 'CompE' constructor represents a list comprehension, and
    835 -- takes a ['Stmt'].  The result expression of the comprehension is
    836 -- the *last* of these, and should be a 'NoBindS'.
    837 --
    838 -- E.g. translation:
    839 --
    840 -- > [ f x | x <- xs ]
    841 --
    842 -- > CompE [BindS (VarP x) (VarE xs), NoBindS (AppE (VarE f) (VarE x))]
    8431080data Exp
    8441081  = VarE Name                          -- ^ @{ x }@
    8451082  | ConE Name                          -- ^ @data T1 = C1 t1 t2; p = {C1} e1 e2  @
    data Exp 
    8471084  | AppE Exp Exp                       -- ^ @{ f x }@
    8481085
    8491086  | InfixE (Maybe Exp) Exp (Maybe Exp) -- ^ @{x + y} or {(x+)} or {(+ x)} or {(+)}@
    850     --
     1087
    8511088    -- It's a bit gruesome to use an Exp as the
    8521089    -- operator, but how else can we distinguish
    8531090    -- constructors from non-constructors?
    data Exp 
    8561093
    8571094  | UInfixE Exp Exp Exp                -- ^ @{x + y}@
    8581095                                       --
    859                                        -- See Note [Unresolved infix] at "Language.Haskell.TH.Syntax#infix"
     1096                                       -- See "Language.Haskell.TH.Syntax#infix"
    8601097  | ParensE Exp                        -- ^ @{ (e) }@
    8611098                                       --
    862                                        -- See Note [Unresolved infix] at "Language.Haskell.TH.Syntax#infix"
     1099                                       -- See "Language.Haskell.TH.Syntax#infix"
    8631100  | LamE [Pat] Exp                     -- ^ @{ \ p1 p2 -> e }@
    8641101  | TupE [Exp]                         -- ^ @{ (e1,e2) }  @
    8651102  | UnboxedTupE [Exp]                  -- ^ @{ (# e1,e2 #) }  @
    data Exp 
    8671104  | LetE [Dec] Exp                     -- ^ @{ let x=e1;   y=e2 in e3 }@
    8681105  | CaseE Exp [Match]                  -- ^ @{ case e of m1; m2 }@
    8691106  | DoE [Stmt]                         -- ^ @{ do { p <- e1; e2 }  }@
    870   | CompE [Stmt]                       -- ^ @{ [ (x,y) | x <- xs, y <- ys ] }@
     1107  | CompE [Stmt]                       -- ^ @{ [ (x,y) | x <- xs, y <- ys ] }@
     1108      --
     1109      -- The result expression of the comprehension is
     1110      -- the /last/ of the @'Stmt'@s, and should be a 'NoBindS'.
     1111      --
     1112      -- E.g. translation:
     1113      --
     1114      -- > [ f x | x <- xs ]
     1115      --
     1116      -- > CompE [BindS (VarP x) (VarE xs), NoBindS (AppE (VarE f) (VarE x))]
     1117
    8711118  | ArithSeqE Range                    -- ^ @{ [ 1 ,2 .. 10 ] }@
    8721119  | ListE [ Exp ]                      -- ^ @{ [1,2,3] }@
    8731120  | SigE Exp Type                      -- ^ @{ e :: t }@
    type FieldExp = (Name,Exp) 
    8801127-- Omitted: implicit parameters
    8811128
    8821129data Body
    883   = GuardedB [(Guard,Exp)]   -- ^ @f p { | e1 = e2 | e3 = e4 } where ds@
     1130  = GuardedB [(Guard,Exp)]   -- ^ @f p { | e1 = e2
     1131                                 --      | e3 = e4 }
     1132                                 -- where ds@
    8841133  | NormalB Exp              -- ^ @f p { = e } where ds@
    8851134  deriving( Show, Eq, Data, Typeable )
    8861135
    8871136data Guard
    888   = NormalG Exp
    889   | PatG [Stmt]
     1137  = NormalG Exp -- ^ @f x { | odd x } = x@
     1138  | PatG [Stmt] -- ^ @f x { | Just y <- x, Just z <- y } = z@
    8901139  deriving( Show, Eq, Data, Typeable )
    8911140
    8921141data Stmt
    data Dec 
    9151164  | InstanceD Cxt Type [Dec]      -- ^ @{ instance Show w => Show [w]
    9161165                                  --       where ds }@
    9171166  | SigD Name Type                -- ^ @{ length :: [a] -> Int }@
    918   | ForeignD Foreign
     1167  | ForeignD Foreign              -- ^ @{ foreign import ... }
     1168                                  --{ foreign export ... }@
    9191169
    9201170  | InfixD Fixity Name            -- ^ @{ infix 3 foo }@
    9211171
    9221172  -- | pragmas
    923   | PragmaD Pragma                -- ^ @{ {-# INLINE [1] foo #-} }@
     1173  | PragmaD Pragma                -- ^ @{ {\-# INLINE [1] foo #-\} }@
    9241174
    9251175  -- | type families (may also appear in [Dec] of 'ClassD' and 'InstanceD')
    9261176  | FamilyD FamFlavour Name
    data Con = NormalC Name [StrictType] -- ^ @C Int a@ 
    9851235type StrictType = (Strict, Type)
    9861236type VarStrictType = (Name, Strict, Type)
    9871237
    988 data Type = ForallT [TyVarBndr] Cxt Type  -- ^ @forall <vars>. <ctxt> -> <type>@
     1238data Type = ForallT [TyVarBndr] Cxt Type  -- ^ @forall \<vars\>. \<ctxt\> -> \<type\>@
    9891239          | AppT Type Type                -- ^ @T a b@
    9901240          | SigT Type Kind                -- ^ @t :: k@
    9911241          | VarT Name                     -- ^ @a@