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

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

    From b12b86922aac32569d64fdaabba44bae28f052e7 Mon Sep 17 00:00:00 2001
    From: Dan Frumin <difrumin@gmail.com>
    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