Ticket #8201: 0001-Haddockify-the-documentation-in-HsBinds.patch

File 0001-Haddockify-the-documentation-in-HsBinds.patch, 9.6 KB (added by DaniilFrumin, 2 years ago)
  • compiler/hsSyn/HsBinds.lhs

    From b12b86922aac32569d64fdaabba44bae28f052e7 Mon Sep 17 00:00:00 2001
    From: Dan Frumin <[email protected]>
    Date: Thu, 29 Aug 2013 20:14:02 +0000
    Subject: [PATCH 1/2] Haddockify the documentation in HsBinds
    
    ---
     compiler/hsSyn/HsBinds.lhs |  127 ++++++++++++++++++++++++++------------------
     1 file changed, 74 insertions(+), 53 deletions(-)
    
    diff --git a/compiler/hsSyn/HsBinds.lhs b/compiler/hsSyn/HsBinds.lhs
    index cb2538f..db4c177 100644
    a b Global bindings (where clauses) 
    5353
    5454type HsLocalBinds id = HsLocalBindsLR id id
    5555
    56 data HsLocalBindsLR idL idR    -- Bindings in a 'let' expression
    57                                -- or a 'where' clause
     56-- | Bindings in a 'let' expression
     57-- or a 'where' clause
     58data HsLocalBindsLR idL idR   
    5859  = HsValBinds (HsValBindsLR idL idR)
    5960  | HsIPBinds  (HsIPBinds idR)
    6061  | EmptyLocalBinds
    data HsLocalBindsLR idL idR -- Bindings in a 'let' expression 
    6263
    6364type HsValBinds id = HsValBindsLR id id
    6465
    65 data HsValBindsLR idL idR  -- Value bindings (not implicit parameters)
    66   = ValBindsIn             -- Before renaming RHS; idR is always RdrName
    67         (LHsBindsLR idL idR) [LSig idR] -- Not dependency analysed
    68                                         -- Recursive by default
    69 
    70   | ValBindsOut            -- After renaming RHS; idR can be Name or Id
    71         [(RecFlag, LHsBinds idL)]       -- Dependency analysed, later bindings
    72                                         -- in the list may depend on earlier
    73                                         -- ones.
     66-- | Value bindings (not implicit parameters)
     67data HsValBindsLR idL idR   
     68  = -- | Before renaming RHS; idR is always RdrName
     69    -- Not dependency analysed
     70    -- Recursive by default
     71    ValBindsIn
     72        (LHsBindsLR idL idR) [LSig idR]
     73
     74    -- | After renaming RHS; idR can be Name or Id
     75    --  Dependency analysed,
     76    -- later bindings in the list may depend on earlier
     77    -- ones.
     78  | ValBindsOut           
     79        [(RecFlag, LHsBinds idL)]       
    7480        [LSig Name]
    7581  deriving (Data, Typeable)
    7682
    data HsBindLR idL idR 
    121127        fun_tick :: Maybe (Tickish Id)  -- ^ Tick to put on the rhs, if any
    122128    }
    123129
    124   | PatBind {   -- The pattern is never a simple variable;
    125                 -- That case is done by FunBind
     130  -- | The pattern is never a simple variable;
     131  -- That case is done by FunBind
     132  | PatBind {   
    126133        pat_lhs    :: LPat idL,
    127134        pat_rhs    :: GRHSs idR (LHsExpr idR),
    128         pat_rhs_ty :: PostTcType,       -- Type of the GRHSs
    129         bind_fvs   :: NameSet,          -- See Note [Bind free vars]
     135        pat_rhs_ty :: PostTcType,       -- ^ Type of the GRHSs
     136        bind_fvs   :: NameSet,          -- ^ See Note [Bind free vars]
    130137        pat_ticks  :: (Maybe (Tickish Id), [Maybe (Tickish Id)])
    131138               -- ^ Tick to put on the rhs, if any, and ticks to put on
    132139               -- the bound variables.
    133140    }
    134141
    135   | VarBind {   -- Dictionary binding and suchlike
    136         var_id     :: idL,           -- All VarBinds are introduced by the type checker
    137         var_rhs    :: LHsExpr idR,   -- Located only for consistency
    138         var_inline :: Bool           -- True <=> inline this binding regardless
     142  -- | Dictionary binding and suchlike.
     143  -- All VarBinds are introduced by the type checker
     144  | VarBind {   
     145        var_id     :: idL,           
     146        var_rhs    :: LHsExpr idR,   -- ^ Located only for consistency
     147        var_inline :: Bool           -- ^ True <=> inline this binding regardless
    139148                                     -- (used for implication constraints only)
    140149    }
    141150
    142   | AbsBinds {                          -- Binds abstraction; TRANSLATION
     151  | AbsBinds {                      -- Binds abstraction; TRANSLATION
    143152        abs_tvs     :: [TyVar],
    144         abs_ev_vars :: [EvVar],  -- Includes equality constraints
     153        abs_ev_vars :: [EvVar],  -- ^ Includes equality constraints
    145154
    146        -- AbsBinds only gets used when idL = idR after renaming,
     155       -- | AbsBinds only gets used when idL = idR after renaming,
    147156       -- but these need to be idL's for the collect... code in HsUtil
    148157       -- to have the right type
    149158        abs_exports :: [ABExport idL],
    150159
    151         abs_ev_binds :: TcEvBinds,     -- Evidence bindings
    152         abs_binds    :: LHsBinds idL   -- Typechecked user bindings
     160        abs_ev_binds :: TcEvBinds,     -- ^ Evidence bindings
     161        abs_binds    :: LHsBinds idL   -- ^ Typechecked user bindings
    153162    }
    154163
    155164  deriving (Data, Typeable)
    data HsBindLR idL idR 
    166175        -- See Note [AbsBinds]
    167176
    168177data ABExport id
    169   = ABE { abe_poly  :: id           -- Any INLINE pragmas is attached to this Id
     178  = ABE { abe_poly  :: id           -- ^ Any INLINE pragmas is attached to this Id
    170179        , abe_mono  :: id
    171         , abe_wrap  :: HsWrapper    -- See Note [AbsBinds wrappers]
     180        , abe_wrap  :: HsWrapper    -- ^ See Note [AbsBinds wrappers]
    172181             -- Shape: (forall abs_tvs. abs_ev_vars => abe_mono) ~ abe_poly
    173         , abe_prags :: TcSpecPrags  -- SPECIALISE pragmas
     182        , abe_prags :: TcSpecPrags  -- ^ SPECIALISE pragmas
    174183  } deriving (Data, Typeable)
    175184
     185-- | Used for the NameSet in FunBind and PatBind prior to the renamer
    176186placeHolderNames :: NameSet
    177 -- Used for the NameSet in FunBind and PatBind prior to the renamer
    178187placeHolderNames = panic "placeHolderNames"
    179188\end{code}
    180189
    serves for both. 
    501510\begin{code}
    502511type LSig name = Located (Sig name)
    503512
    504 data Sig name   -- Signatures and pragmas
    505   =     -- An ordinary type signature
    506         -- f :: Num a => a -> a
     513-- | Signatures and pragmas
     514data Sig name   
     515  =   -- | An ordinary type signature
     516      -- @f :: Num a => a -> a@
    507517    TypeSig [Located name] (LHsType name)
    508518
    509         -- A type signature for a default method inside a class
    510         -- default eq :: (Representable0 a, GEq (Rep0 a)) => a -> a -> Bool
     519        -- | A type signature for a default method inside a class
     520        --
     521        -- > default eq :: (Representable0 a, GEq (Rep0 a)) => a -> a -> Bool
     522        --
    511523  | GenericSig [Located name] (LHsType name)
    512524
    513         -- A type signature in generated code, notably the code
     525        -- | A type signature in generated code, notably the code
    514526        -- generated for record selectors.  We simply record
    515527        -- the desired Id itself, replete with its name, type
    516528        -- and IdDetails.  Otherwise it's just like a type
    517529        -- signature: there should be an accompanying binding
    518530  | IdSig Id
    519531
    520         -- An ordinary fixity declaration
    521         --      infixl *** 8
     532        -- | An ordinary fixity declaration
     533        --
     534        -- >     infixl *** 8
     535        --
    522536  | FixSig (FixitySig name)
    523537
    524         -- An inline pragma
    525         -- {#- INLINE f #-}
     538        -- | An inline pragma
     539        --
     540        -- > {#- INLINE f #-}
     541        --
    526542  | InlineSig   (Located name)  -- Function name
    527543                InlinePragma    -- Never defaultInlinePragma
    528544
    529         -- A specialisation pragma
    530         -- {-# SPECIALISE f :: Int -> Int #-}
    531   | SpecSig     (Located name)  -- Specialise a function or datatype ...
     545        -- | A specialisation pragma
     546        --
     547        -- > {-# SPECIALISE f :: Int -> Int #-}
     548        --
     549  | SpecSig     (Located name)  -- Specialise a function or datatype  ...
    532550                (LHsType name)  -- ... to these types
    533                 InlinePragma    -- The pragma on SPECIALISE_INLINE form
     551                InlinePragma    -- The pragma on SPECIALISE_INLINE form.
    534552                                -- If it's just defaultInlinePragma, then we said
    535553                                --    SPECIALISE, not SPECIALISE_INLINE
    536554
    537         -- A specialisation pragma for instance declarations only
    538         -- {-# SPECIALISE instance Eq [Int] #-}
    539   | SpecInstSig (LHsType name)  -- (Class tys); should be a specialisation of the
    540                                 -- current instance decl
     555        -- | A specialisation pragma for instance declarations only
     556        --
     557        -- > {-# SPECIALISE instance Eq [Int] #-}
     558        --
     559        -- (Class tys); should be a specialisation of the
     560        -- current instance declaration
     561  | SpecInstSig (LHsType name)
    541562  deriving (Data, Typeable)
    542563
    543564
    type LFixitySig name = Located (FixitySig name) 
    545566data FixitySig name = FixitySig (Located name) Fixity
    546567  deriving (Data, Typeable)
    547568
    548 -- TsSpecPrags conveys pragmas from the type checker to the desugarer
     569-- | TsSpecPrags conveys pragmas from the type checker to the desugarer
    549570data TcSpecPrags
    550   = IsDefaultMethod     -- Super-specialised: a default method should
     571  = IsDefaultMethod     -- ^ Super-specialised: a default method should
    551572                        -- be macro-expanded at every call site
    552573  | SpecPrags [LTcSpecPrag]
    553574  deriving (Data, Typeable)
    type LTcSpecPrag = Located TcSpecPrag 
    556577
    557578data TcSpecPrag
    558579  = SpecPrag
    559         Id              -- The Id to be specialised
    560         HsWrapper       -- An wrapper, that specialises the polymorphic function
    561         InlinePragma    -- Inlining spec for the specialised function
     580        Id             
     581        HsWrapper       
     582        InlinePragma   
     583  -- ^ The Id to be specialised, an wrapper that specialises the
     584  -- polymorphic function, and inlining spec for the specialised function
    562585  deriving (Data, Typeable)
    563586
    564587noSpecPrags :: TcSpecPrags
    isDefaultMethod :: TcSpecPrags -> Bool 
    572595isDefaultMethod IsDefaultMethod = True
    573596isDefaultMethod (SpecPrags {})  = False
    574597
    575 \end{code}
    576598
    577 \begin{code}
    578599isFixityLSig :: LSig name -> Bool
    579600isFixityLSig (L _ (FixSig {})) = True
    580601isFixityLSig _                 = False