Structure H.Types better

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