Commit e63e94a2 authored by Thomas Schilling's avatar Thomas Schilling

Improve Haddock-markup for HsDecls module.

parent 177b55f1
...@@ -3,10 +3,7 @@ ...@@ -3,10 +3,7 @@
% (c) The GRASP/AQUA Project, Glasgow University, 1992-1998 % (c) The GRASP/AQUA Project, Glasgow University, 1992-1998
% %
HsDecls: Abstract syntax: global declarations
Definitions for: @TyDecl@ and @oCnDecl@, @ClassDecl@,
@InstDecl@, @DefaultDecl@ and @ForeignDecl@.
\begin{code} \begin{code}
{-# OPTIONS -fno-warn-incomplete-patterns #-} {-# OPTIONS -fno-warn-incomplete-patterns #-}
...@@ -16,26 +13,44 @@ Definitions for: @TyDecl@ and @oCnDecl@, @ClassDecl@, ...@@ -16,26 +13,44 @@ Definitions for: @TyDecl@ and @oCnDecl@, @ClassDecl@,
-- http://hackage.haskell.org/trac/ghc/wiki/Commentary/CodingStyle#Warnings -- http://hackage.haskell.org/trac/ghc/wiki/Commentary/CodingStyle#Warnings
-- for details -- for details
-- | Abstract syntax of global declarations.
--
-- Definitions for: @TyDecl@ and @ConDecl@, @ClassDecl@,
-- @InstDecl@, @DefaultDecl@ and @ForeignDecl@.
module HsDecls ( module HsDecls (
HsDecl(..), LHsDecl, TyClDecl(..), LTyClDecl, -- * Toplevel declarations
InstDecl(..), LInstDecl, DerivDecl(..), LDerivDecl, NewOrData(..), HsDecl(..), LHsDecl,
FamilyFlavour(..), -- ** Class or type declarations
RuleDecl(..), LRuleDecl, RuleBndr(..), TyClDecl(..), LTyClDecl,
DefaultDecl(..), LDefaultDecl, SpliceDecl(..), isClassDecl, isSynDecl, isDataDecl, isTypeDecl, isFamilyDecl,
ForeignDecl(..), LForeignDecl, ForeignImport(..), ForeignExport(..), isFamInstDecl, tcdName, tyClDeclNames, tyClDeclTyVars,
CImportSpec(..), FoType(..), countTyClDecls,
ConDecl(..), ResType(..), ConDeclField(..), LConDecl, -- ** Instance declarations
HsConDeclDetails, hsConDeclArgTys, InstDecl(..), LInstDecl, NewOrData(..), FamilyFlavour(..),
DocDecl(..), LDocDecl, docDeclDoc, instDeclATs,
WarnDecl(..), LWarnDecl, -- ** Standalone deriving declarations
HsGroup(..), emptyRdrGroup, emptyRnGroup, appendGroups, DerivDecl(..), LDerivDecl,
tcdName, tyClDeclNames, tyClDeclTyVars, -- ** @RULE@ declarations
isClassDecl, isSynDecl, isDataDecl, isTypeDecl, isFamilyDecl, RuleDecl(..), LRuleDecl, RuleBndr(..),
isFamInstDecl, collectRuleBndrSigTys,
countTyClDecls, -- ** @default@ declarations
instDeclATs, DefaultDecl(..), LDefaultDecl,
collectRuleBndrSigTys, -- ** Top-level template haskell splice
) where SpliceDecl(..),
-- ** Foreign function interface declarations
ForeignDecl(..), LForeignDecl, ForeignImport(..), ForeignExport(..),
CImportSpec(..), FoType(..),
-- ** Data-constructor declarations
ConDecl(..), LConDecl, ResType(..), ConDeclField(..),
HsConDeclDetails, hsConDeclArgTys,
-- ** Document comments
DocDecl(..), LDocDecl, docDeclDoc,
-- ** Deprecations
WarnDecl(..), LWarnDecl,
-- * Grouping
HsGroup(..), emptyRdrGroup, emptyRnGroup, appendGroups,
) where
-- friends: -- friends:
import {-# SOURCE #-} HsExpr( HsExpr, pprExpr ) import {-# SOURCE #-} HsExpr( HsExpr, pprExpr )
...@@ -69,9 +84,10 @@ import Data.Maybe ( isJust ) ...@@ -69,9 +84,10 @@ import Data.Maybe ( isJust )
\begin{code} \begin{code}
type LHsDecl id = Located (HsDecl id) type LHsDecl id = Located (HsDecl id)
-- | A Haskell Declaration
data HsDecl id data HsDecl id
= TyClD (TyClDecl id) = TyClD (TyClDecl id) -- ^ A type or class declaration.
| InstD (InstDecl id) | InstD (InstDecl id) -- ^ An instance declaration.
| DerivD (DerivDecl id) | DerivD (DerivDecl id)
| ValD (HsBind id) | ValD (HsBind id)
| SigD (Sig id) | SigD (Sig id)
...@@ -96,7 +112,7 @@ data HsDecl id ...@@ -96,7 +112,7 @@ data HsDecl id
-- --
-- The latter is for class methods only -- The latter is for class methods only
-- A [HsDecl] is categorised into a HsGroup before being -- | A 'HsDecl' is categorised into a 'HsGroup' before being
-- fed to the renamer. -- fed to the renamer.
data HsGroup id data HsGroup id
= HsGroup { = HsGroup {
...@@ -369,6 +385,7 @@ Interface file code: ...@@ -369,6 +385,7 @@ Interface file code:
type LTyClDecl name = Located (TyClDecl name) type LTyClDecl name = Located (TyClDecl name)
-- | A type or class declaration.
data TyClDecl name data TyClDecl name
= ForeignType { = ForeignType {
tcdLName :: Located name, tcdLName :: Located name,
...@@ -376,105 +393,122 @@ data TyClDecl name ...@@ -376,105 +393,122 @@ data TyClDecl name
tcdFoType :: FoType tcdFoType :: FoType
} }
-- type/data/newtype family T :: *->*
| TyFamily { tcdFlavour:: FamilyFlavour, -- type, new, or data | -- | @type/data/newtype family T :: *->*@
TyFamily { tcdFlavour:: FamilyFlavour, -- type, new, or data
tcdLName :: Located name, -- type constructor tcdLName :: Located name, -- type constructor
tcdTyVars :: [LHsTyVarBndr name], -- type variables tcdTyVars :: [LHsTyVarBndr name], -- type variables
tcdKind :: Maybe Kind -- result kind tcdKind :: Maybe Kind -- result kind
} }
-- Declares a data type or newtype, giving its construcors
-- data/newtype T a = <constrs>
-- data/newtype instance T [a] = <constrs>
| TyData { tcdND :: NewOrData,
tcdCtxt :: LHsContext name, -- Context
tcdLName :: Located name, -- Type constructor
tcdTyVars :: [LHsTyVarBndr name], -- Type variables
tcdTyPats :: Maybe [LHsType name], -- Type patterns
-- Just [t1..tn] for data instance T t1..tn = ...
-- in this case tcdTyVars = fv( tcdTyPats )
-- Nothing for everything else
tcdKindSig:: Maybe Kind, -- Optional kind sig | -- | Declares a data type or newtype, giving its construcors
-- (Just k) for a GADT-style 'data', or 'data -- @
-- instance' decl with explicit kind sig -- data/newtype T a = <constrs>
-- data/newtype instance T [a] = <constrs>
-- @
TyData { tcdND :: NewOrData,
tcdCtxt :: LHsContext name, -- ^ Context
tcdLName :: Located name, -- ^ Type constructor
tcdCons :: [LConDecl name], -- Data constructors tcdTyVars :: [LHsTyVarBndr name], -- ^ Type variables
-- For data T a = T1 | T2 a
-- the LConDecls all have ResTyH98 tcdTyPats :: Maybe [LHsType name],
-- For data T a where { T1 :: T a } -- ^ Type patterns.
-- the LConDecls all have ResTyGADT --
-- @Just [t1..tn]@ for @data instance T t1..tn = ...@
-- in this case @tcdTyVars = fv( tcdTyPats )@.
-- @Nothing@ for everything else.
tcdKindSig:: Maybe Kind,
-- ^ Optional kind signature.
--
-- @(Just k)@ for a GADT-style @data@, or @data
-- instance@ decl with explicit kind sig
tcdCons :: [LConDecl name],
-- ^ Data constructors
--
-- For @data T a = T1 | T2 a@
-- the 'LConDecl's all have 'ResTyH98'.
-- For @data T a where { T1 :: T a }@
-- the 'LConDecls' all have 'ResTyGADT'.
tcdDerivs :: Maybe [LHsType name] tcdDerivs :: Maybe [LHsType name]
-- Derivings; Nothing => not specified -- ^ Derivings; @Nothing@ => not specified,
-- Just [] => derive exactly what is asked -- @Just []@ => derive exactly what is asked
--
-- These "types" must be of form -- These "types" must be of form
-- @
-- forall ab. C ty1 ty2 -- forall ab. C ty1 ty2
-- @
-- Typically the foralls and ty args are empty, but they -- Typically the foralls and ty args are empty, but they
-- are non-empty for the newtype-deriving case -- are non-empty for the newtype-deriving case
} }
| TySynonym { tcdLName :: Located name, -- type constructor | TySynonym { tcdLName :: Located name, -- ^ type constructor
tcdTyVars :: [LHsTyVarBndr name], -- type variables tcdTyVars :: [LHsTyVarBndr name], -- ^ type variables
tcdTyPats :: Maybe [LHsType name], -- Type patterns tcdTyPats :: Maybe [LHsType name], -- ^ Type patterns
-- See comments for tcdTyPats in TyData -- See comments for tcdTyPats in TyData
-- 'Nothing' => vanilla type synonym -- 'Nothing' => vanilla type synonym
tcdSynRhs :: LHsType name -- synonym expansion tcdSynRhs :: LHsType name -- ^ synonym expansion
} }
| ClassDecl { tcdCtxt :: LHsContext name, -- Context... | ClassDecl { tcdCtxt :: LHsContext name, -- ^ Context...
tcdLName :: Located name, -- Name of the class tcdLName :: Located name, -- ^ Name of the class
tcdTyVars :: [LHsTyVarBndr name], -- Class type variables tcdTyVars :: [LHsTyVarBndr name], -- ^ Class type variables
tcdFDs :: [Located (FunDep name)], -- Functional deps tcdFDs :: [Located (FunDep name)], -- ^ Functional deps
tcdSigs :: [LSig name], -- Methods' signatures tcdSigs :: [LSig name], -- ^ Methods' signatures
tcdMeths :: LHsBinds name, -- Default methods tcdMeths :: LHsBinds name, -- ^ Default methods
tcdATs :: [LTyClDecl name], -- Associated types; ie tcdATs :: [LTyClDecl name], -- ^ Associated types; ie
-- only 'TyFamily' and -- only 'TyFamily' and
-- 'TySynonym'; the -- 'TySynonym'; the
-- latter for defaults -- latter for defaults
tcdDocs :: [LDocDecl name] -- Haddock docs tcdDocs :: [LDocDecl name] -- ^ Haddock docs
} }
data NewOrData data NewOrData
= NewType -- "newtype Blah ..." = NewType -- ^ @newtype Blah ...@
| DataType -- "data Blah ..." | DataType -- ^ @data Blah ...@
deriving( Eq ) -- Needed because Demand derives Eq deriving( Eq ) -- Needed because Demand derives Eq
data FamilyFlavour data FamilyFlavour
= TypeFamily -- "type family ..." = TypeFamily -- ^ @type family ...@
| DataFamily -- "data family ..." | DataFamily -- ^ @data family ...@
\end{code} \end{code}
Simple classifiers Simple classifiers
\begin{code} \begin{code}
isDataDecl, isTypeDecl, isSynDecl, isClassDecl, isFamilyDecl, isFamInstDecl :: -- | @True@ <=> argument is a @data@\/@newtype@ or @data@\/@newtype instance@
TyClDecl name -> Bool -- declaration.
isDataDecl :: TyClDecl name -> Bool
-- data/newtype or data/newtype instance declaration
isDataDecl (TyData {}) = True isDataDecl (TyData {}) = True
isDataDecl _other = False isDataDecl _other = False
-- type or type instance declaration -- | type or type instance declaration
isTypeDecl :: TyClDecl name -> Bool
isTypeDecl (TySynonym {}) = True isTypeDecl (TySynonym {}) = True
isTypeDecl _other = False isTypeDecl _other = False
-- vanilla Haskell type synonym (ie, not a type instance) -- | vanilla Haskell type synonym (ie, not a type instance)
isSynDecl :: TyClDecl name -> Bool
isSynDecl (TySynonym {tcdTyPats = Nothing}) = True isSynDecl (TySynonym {tcdTyPats = Nothing}) = True
isSynDecl _other = False isSynDecl _other = False
-- type class -- | type class
isClassDecl :: TyClDecl name -> Bool
isClassDecl (ClassDecl {}) = True isClassDecl (ClassDecl {}) = True
isClassDecl _ = False isClassDecl _ = False
-- type family declaration -- | type family declaration
isFamilyDecl :: TyClDecl name -> Bool
isFamilyDecl (TyFamily {}) = True isFamilyDecl (TyFamily {}) = True
isFamilyDecl _other = False isFamilyDecl _other = False
-- family instance (types, newtypes, and data types) -- | family instance (types, newtypes, and data types)
isFamInstDecl :: TyClDecl name -> Bool
isFamInstDecl tydecl isFamInstDecl tydecl
| isTypeDecl tydecl | isTypeDecl tydecl
|| isDataDecl tydecl = isJust (tcdTyPats tydecl) || isDataDecl tydecl = isJust (tcdTyPats tydecl)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment