diff options
| -rw-r--r-- | src/Haddock/Types.hs | 291 |
1 files changed, 168 insertions, 123 deletions
diff --git a/src/Haddock/Types.hs b/src/Haddock/Types.hs index fa0e9a13..3739df98 100644 --- a/src/Haddock/Types.hs +++ b/src/Haddock/Types.hs @@ -32,134 +32,21 @@ import Name import Test.QuickCheck #endif - --- | Convenient short-hand -type Decl = LHsDecl Name - - --- | An instance head that may have documentation. -type DocInstance name = (InstHead name, Maybe (Doc name)) - - --- | Arguments and result are indexed by Int, zero-based from the left, --- because that's the easiest to use when recursing over types. -type FnArgsDoc name = Map Int (Doc name) -type DocForDecl name = (Maybe (Doc name), FnArgsDoc name) - - -noDocForDecl :: DocForDecl name -noDocForDecl = (Nothing, Map.empty) - - --- | A declaration that may have documentation, including its subordinates, --- which may also have documentation -type DeclInfo = (Decl, DocForDecl Name, [(Name, DocForDecl Name)]) - - --- | An extension of 'Name' that may contain the preferred place to link to in --- the documentation. -data DocName = Documented Name Module | Undocumented Name deriving Eq --- TODO: simplify to data DocName = DocName Name (Maybe Module) - - --- | The 'OccName' of this name. -docNameOcc :: DocName -> OccName -docNameOcc = nameOccName . getName - - -instance NamedThing DocName where - getName (Documented name _) = name - getName (Undocumented name) = name - - -{-! for DocOption derive: Binary !-} --- | Source-level options for controlling the documentation. -data DocOption - = OptHide -- ^ This module should not appear in the docs - | OptPrune - | OptIgnoreExports -- ^ Pretend everything is exported - | OptNotHome -- ^ Not the best place to get docs for things - -- exported by this module. - deriving (Eq, Show) - - -data ExportItem name - - = ExportDecl { - - -- | A declaration - expItemDecl :: LHsDecl name, - - -- | Maybe a doc comment, and possibly docs for arguments (if this - -- decl is a function or type-synonym) - expItemMbDoc :: DocForDecl name, - - -- | Subordinate names, possibly with documentation - expItemSubDocs :: [(name, DocForDecl name)], - - -- | Instances relevant to this declaration, possibly with documentation - expItemInstances :: [DocInstance name] - - } -- ^ An exported declaration - - | ExportNoDecl { - expItemName :: name, - - -- | Subordinate names - expItemSubs :: [name] - - } -- ^ An exported entity for which we have no - -- documentation (perhaps because it resides in - -- another package) - - | ExportGroup { - - -- | Section level (1, 2, 3, ... ) - expItemSectionLevel :: Int, - - -- | Section id (for hyperlinks) - expItemSectionId :: String, - - -- | Section heading text - expItemSectionText :: Doc name - - } -- ^ A section heading - - | ExportDoc (Doc name) -- ^ Some documentation - - | ExportModule Module -- ^ A cross-reference to another module - - --- | The head of an instance. Consists of a context, a class name and a list of --- instance types. -type InstHead name = ([HsPred name], name, [HsType name]) +----------------------------------------------------------------------------- +-- * Convenient synonyms +----------------------------------------------------------------------------- type IfaceMap = Map Module Interface type InstIfaceMap = Map Module InstalledInterface type DocMap = Map Name (Doc DocName) --- | An environment used to create hyper-linked syntax. -type LinkEnv = Map Name Module - +type Decl = LHsDecl Name +type GhcDocHdr = Maybe LHsDocString -type GhcDocHdr = Maybe LHsDocString - --- | This structure holds the module information we get from GHC's --- type checking phase -data GhcModule = GhcModule { - ghcModule :: Module, - ghcFilename :: FilePath, - ghcMbDocOpts :: Maybe String, - ghcMbDocHdr :: GhcDocHdr, - ghcGroup :: HsGroup Name, - ghcMbExports :: Maybe [LIE Name], - ghcExportedNames :: [Name], - ghcDefinedNames :: [Name], - ghcNamesInScope :: [Name], - ghcInstances :: [Instance], - ghcDynFlags :: DynFlags -} +----------------------------------------------------------------------------- +-- * Interface +----------------------------------------------------------------------------- -- | The data structure used to render a Haddock page for a module - it is @@ -258,8 +145,71 @@ toInstalledIface interface = InstalledInterface { } -unrenameDoc :: Doc DocName -> Doc Name -unrenameDoc = fmap getName +----------------------------------------------------------------------------- +-- * Export items & declarations +----------------------------------------------------------------------------- + + +data ExportItem name + + = ExportDecl { + + -- | A declaration + expItemDecl :: LHsDecl name, + + -- | Maybe a doc comment, and possibly docs for arguments (if this + -- decl is a function or type-synonym) + expItemMbDoc :: DocForDecl name, + + -- | Subordinate names, possibly with documentation + expItemSubDocs :: [(name, DocForDecl name)], + + -- | Instances relevant to this declaration, possibly with documentation + expItemInstances :: [DocInstance name] + + } -- ^ An exported declaration + + | ExportNoDecl { + expItemName :: name, + + -- | Subordinate names + expItemSubs :: [name] + + } -- ^ An exported entity for which we have no + -- documentation (perhaps because it resides in + -- another package) + + | ExportGroup { + + -- | Section level (1, 2, 3, ... ) + expItemSectionLevel :: Int, + + -- | Section id (for hyperlinks) + expItemSectionId :: String, + + -- | Section heading text + expItemSectionText :: Doc name + + } -- ^ A section heading + + | ExportDoc (Doc name) -- ^ Some documentation + + | ExportModule Module -- ^ A cross-reference to another module + + +-- | A declaration that may have documentation, including its subordinates, +-- which may also have documentation +type DeclInfo = (Decl, DocForDecl Name, [(Name, DocForDecl Name)]) + + +-- | Arguments and result are indexed by Int, zero-based from the left, +-- because that's the easiest to use when recursing over types. +type FnArgsDoc name = Map Int (Doc name) +type DocForDecl name = (Maybe (Doc name), FnArgsDoc name) + + +noDocForDecl :: DocForDecl name +noDocForDecl = (Nothing, Map.empty) unrenameDocForDecl :: DocForDecl DocName -> DocForDecl Name @@ -267,6 +217,53 @@ unrenameDocForDecl (mbDoc, fnArgsDoc) = (fmap unrenameDoc mbDoc, fmap unrenameDoc fnArgsDoc) +----------------------------------------------------------------------------- +-- * Hyperlinking +----------------------------------------------------------------------------- + + +-- | An environment used to create hyper-linked syntax. +type LinkEnv = Map Name Module + + +-- | An extension of 'Name' that may contain the preferred place to link to in +-- the documentation. +data DocName = Documented Name Module | Undocumented Name deriving Eq +-- TODO: simplify to data DocName = DocName Name (Maybe Module) + + +-- | The 'OccName' of this name. +docNameOcc :: DocName -> OccName +docNameOcc = nameOccName . getName + + +instance NamedThing DocName where + getName (Documented name _) = name + getName (Undocumented name) = name + + +----------------------------------------------------------------------------- +-- * Instances +----------------------------------------------------------------------------- + + +-- | An instance head that may have documentation. +type DocInstance name = (InstHead name, Maybe (Doc name)) + + +-- | The head of an instance. Consists of a context, a class name and a list of +-- instance types. +type InstHead name = ([HsPred name], name, [HsType name]) + + +----------------------------------------------------------------------------- +-- * Documentation comments +----------------------------------------------------------------------------- + + +type LDoc id = Located (Doc id) + + data Doc id = DocEmpty | DocAppend (Doc id) (Doc id) @@ -287,6 +284,10 @@ data Doc id deriving (Eq, Show, Functor) +unrenameDoc :: Doc DocName -> Doc Name +unrenameDoc = fmap getName + + data Example = Example { exampleExpression :: String , exampleResult :: [String] @@ -360,6 +361,50 @@ emptyHaddockModInfo = HaddockModInfo { } +----------------------------------------------------------------------------- +-- * Options +----------------------------------------------------------------------------- + + +{-! for DocOption derive: Binary !-} +-- | Source-level options for controlling the documentation. +data DocOption + = OptHide -- ^ This module should not appear in the docs + | OptPrune + | OptIgnoreExports -- ^ Pretend everything is exported + | OptNotHome -- ^ Not the best place to get docs for things + -- exported by this module. + deriving (Eq, Show) + + +----------------------------------------------------------------------------- +-- * Misc. +----------------------------------------------------------------------------- + + +-- TODO: remove? +-- | This structure holds the module information we get from GHC's +-- type checking phase +data GhcModule = GhcModule { + ghcModule :: Module, + ghcFilename :: FilePath, + ghcMbDocOpts :: Maybe String, + ghcMbDocHdr :: GhcDocHdr, + ghcGroup :: HsGroup Name, + ghcMbExports :: Maybe [LIE Name], + ghcExportedNames :: [Name], + ghcDefinedNames :: [Name], + ghcNamesInScope :: [Name], + ghcInstances :: [Instance], + ghcDynFlags :: DynFlags +} + + +----------------------------------------------------------------------------- +-- * Error handling +----------------------------------------------------------------------------- + + -- A monad which collects error messages, locally defined to avoid a dep on mtl |