aboutsummaryrefslogtreecommitdiff
path: root/src/Haddock
diff options
context:
space:
mode:
Diffstat (limited to 'src/Haddock')
-rw-r--r--src/Haddock/Types.hs291
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
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-14 19:32:17 +0000