Follow the style guide closer in Haddock.Types and improve docs

1 files changed, 147 insertions, 143 deletions

diff --git a/src/Haddock/Types.hs b/src/Haddock/Types.hs
index c00870f9..db8a3198 100644
--- a/src/Haddock/Types.hs
+++ b/src/Haddock/Types.hs
@@ -53,99 +53,100 @@ type DocPaths      = (FilePath, Maybe FilePath) -- paths to HTML and sources
 -- lies in creating this structure. Note that the record contains some fields
 -- that are only used to create the final record, and that are not used by the
 -- backends.
-data Interface = Interface {
+data Interface = Interface
+  {
+    -- | The module behind this interface.
+    ifaceMod             :: Module
 
-  -- | The module represented by this interface.
-  ifaceMod             :: Module,
+    -- | Original file name of the module.
+  , ifaceOrigFilename    :: FilePath
 
-  -- | Original file name of the module.
-  ifaceOrigFilename    :: FilePath,
+    -- | Textual information about the module.
+  , ifaceInfo            :: !(HaddockModInfo Name)
 
-  -- | Textual information about the module.
-  ifaceInfo            :: !(HaddockModInfo Name),
+    -- | Documentation header.
+  , ifaceDoc             :: !(Maybe (Doc Name))
 
-  -- | Documentation header.
-  ifaceDoc             :: !(Maybe (Doc Name)),
+    -- | Documentation header with cross-reference information.
+  , ifaceRnDoc           :: Maybe (Doc DocName)
 
-  -- | Documentation header with link information.
-  ifaceRnDoc           :: Maybe (Doc DocName),
+    -- | Haddock options for this module (prune, ignore-exports, etc).
+  , ifaceOptions         :: ![DocOption]
 
-  -- | Haddock options for this module (prune, ignore-exports, etc).
-  ifaceOptions         :: ![DocOption],
+    -- | Declarations originating from the module. Excludes declarations without
+    -- names (instances and stand-alone documentation comments). Includes
+    -- names of subordinate declarations mapped to their parent declarations.
+  , ifaceDeclMap         :: Map Name DeclInfo
 
-  -- | Declarations originating from the module. Excludes declarations without
-  -- names (instances and stand-alone documentation comments). Includes
-  -- names of subordinate declarations mapped to their parent declarations.
-  ifaceDeclMap         :: Map Name DeclInfo,
+    -- | Documentation of declarations originating from the module (including
+    -- subordinates).
+  , ifaceRnDocMap        :: Map Name (DocForDecl DocName)
 
-  -- | Documentation of declarations originating from the module (including
-  -- subordinates).
-  ifaceRnDocMap        :: Map Name (DocForDecl DocName),
+  , ifaceSubMap          :: Map Name [Name]
 
-  ifaceSubMap          :: Map Name [Name],
+  , ifaceExportItems     :: ![ExportItem Name]
+  , ifaceRnExportItems   :: [ExportItem DocName]
 
-  ifaceExportItems     :: ![ExportItem Name],
-  ifaceRnExportItems   :: [ExportItem DocName],
+    -- | All names exported by the module.
+  , ifaceExports         :: ![Name]
 
-  -- | All names exported by the module.
-  ifaceExports         :: ![Name],
+    -- | All \"visible\" names exported by the module.
+    -- A visible name is a name that will show up in the documentation of the
+    -- module.
+  , ifaceVisibleExports  :: ![Name]
 
-  -- | All \"visible\" names exported by the module.
-  -- A visible name is a name that will show up in the documentation of the
-  -- module.
-  ifaceVisibleExports  :: ![Name],
+    -- | Instances exported by the module.
+  , ifaceInstances       :: ![Instance]
 
-  -- | Instances exported by the module.
-  ifaceInstances       :: ![Instance],
+    -- | Documentation of instances defined in the module.
+  , ifaceInstanceDocMap  :: Map Name (Doc Name)
 
-  -- | Documentation of instances defined in the module.
-  ifaceInstanceDocMap  :: Map Name (Doc Name),
+    -- | The number of haddockable and haddocked items in the module, as a
+    -- tuple. Haddockable items are the exports and the module itself.
+  , ifaceHaddockCoverage  :: (Int,Int)
+  }
 
-  -- | The number of haddockable and haddocked items in the module, as a
-  -- tuple. Haddockable items are the exports and the module itself.
-  ifaceHaddockCoverage  :: (Int,Int)
-}
 
 -- | A subset of the fields of 'Interface' that we store in the interface
 -- files.
-data InstalledInterface = InstalledInterface {
+data InstalledInterface = InstalledInterface
+  {
+    -- | The module represented by this interface.
+    instMod            :: Module
 
-  -- | The module represented by this interface.
-  instMod            :: Module,
+    -- | Textual information about the module.
+  , instInfo           :: HaddockModInfo Name
 
-  -- | Textual information about the module.
-  instInfo           :: HaddockModInfo Name,
+    -- | Documentation of declarations originating from the module (including
+    -- subordinates).
+  , instDocMap         :: Map Name (DocForDecl Name)
 
-  -- | Documentation of declarations originating from the module (including
-  -- subordinates).
-  instDocMap         :: Map Name (DocForDecl Name),
+    -- | All names exported by this module.
+  , instExports        :: [Name]
 
-  -- | All names exported by this module.
-  instExports        :: [Name],
+    -- | All \"visible\" names exported by the module.
+    -- A visible name is a name that will show up in the documentation of the
+    -- module.
+  , instVisibleExports :: [Name]
 
-  -- | All \"visible\" names exported by the module.
-  -- A visible name is a name that will show up in the documentation of the
-  -- module.
-  instVisibleExports :: [Name],
+    -- | Haddock options for this module (prune, ignore-exports, etc).
+  , instOptions        :: [DocOption]
 
-  -- | Haddock options for this module (prune, ignore-exports, etc).
-  instOptions        :: [DocOption],
-
-  instSubMap         :: Map Name [Name]
-}
+  , instSubMap         :: Map Name [Name]
+  }
 
 
 -- | Convert an 'Interface' to an 'InstalledInterface'
 toInstalledIface :: Interface -> InstalledInterface
-toInstalledIface interface = InstalledInterface {
-  instMod            = ifaceMod            interface,
-  instInfo           = ifaceInfo           interface,
-  instDocMap         = fmap unrenameDocForDecl $ ifaceRnDocMap interface,
-  instExports        = ifaceExports        interface,
-  instVisibleExports = ifaceVisibleExports interface,
-  instOptions        = ifaceOptions        interface,
-  instSubMap         = ifaceSubMap         interface
-}
+toInstalledIface interface = InstalledInterface
+  { instMod            = ifaceMod            interface
+  , instInfo           = ifaceInfo           interface
+  , instDocMap         = fmap unrenameDocForDecl $ ifaceRnDocMap interface
+  , instExports        = ifaceExports        interface
+  , instVisibleExports = ifaceVisibleExports interface
+  , instOptions        = ifaceOptions        interface
+  , instSubMap         = ifaceSubMap         interface
+  }
 
 
 -----------------------------------------------------------------------------
@@ -155,53 +156,55 @@ toInstalledIface interface = InstalledInterface {
 
 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)],
+  -- | An exported declaration.
+  = ExportDecl
+      {
+        -- | A declaration.
+        expItemDecl :: LHsDecl name
 
-      -- | Instances relevant to this declaration, possibly with documentation
-      expItemInstances :: [DocInstance name]
+        -- | Maybe a doc comment, and possibly docs for arguments (if this
+        -- decl is a function or type-synonym).
+      , expItemMbDoc :: DocForDecl name
 
-    } -- ^ An exported declaration
+        -- | Subordinate names, possibly with documentation.
+      , expItemSubDocs :: [(name, DocForDecl name)]
 
-  | ExportNoDecl {
-      expItemName :: name,
+        -- | Instances relevant to this declaration, possibly with
+        -- documentation.
+      , expItemInstances :: [DocInstance name]
+      }
 
-      -- | Subordinate names
-      expItemSubs :: [name]
+  -- | An exported entity for which we have no documentation (perhaps because it
+  -- resides in another package).
+  | ExportNoDecl
+      { expItemName :: name
 
-    } -- ^ An exported entity for which we have no
-      -- documentation (perhaps because it resides in
-      -- another package)
+        -- | Subordinate names.
+      , expItemSubs :: [name]
+      }
 
-  | ExportGroup {
+  -- | A section heading. 
+  | ExportGroup
+      {
+        -- | Section level (1, 2, 3, ...).
+        expItemSectionLevel :: Int
 
-      -- | Section level (1, 2, 3, ... )
-      expItemSectionLevel :: Int,
+        -- | Section id (for hyperlinks).
+      , expItemSectionId :: String
 
-      -- | Section id (for hyperlinks)
-      expItemSectionId :: String,
+        -- | Section heading text.
+      , expItemSectionText :: Doc name
+      }
 
-      -- | Section heading text
-      expItemSectionText :: Doc name
+  -- | Some documentation.
+  | ExportDoc (Doc name)
 
-    } -- ^ A section heading
-
-  | ExportDoc (Doc name) -- ^ Some documentation
-
-  | ExportModule Module    -- ^ A cross-reference to another module
+  -- | A cross-reference to another module.
+  | ExportModule Module
 
 
 -- | A declaration that may have documentation, including its subordinates,
--- which may also have documentation
+-- which may also have documentation.
 type DeclInfo = (Decl, DocForDecl Name, [(Name, DocForDecl Name)])
 
 
@@ -255,8 +258,8 @@ instance NamedThing DocName where
 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.
+-- | 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])
 
 
@@ -303,41 +306,41 @@ exampleToString (Example expression result) =
     ">>> " ++ expression ++ "\n" ++  unlines result
 
 
-data DocMarkup id a = Markup {
-  markupEmpty         :: a,
-  markupString        :: String -> a,
-  markupParagraph     :: a -> a,
-  markupAppend        :: a -> a -> a,
-  markupIdentifier    :: [id] -> a,
-  markupModule        :: String -> a,
-  markupEmphasis      :: a -> a,
-  markupMonospaced    :: a -> a,
-  markupUnorderedList :: [a] -> a,
-  markupOrderedList   :: [a] -> a,
-  markupDefList       :: [(a,a)] -> a,
-  markupCodeBlock     :: a -> a,
-  markupURL           :: String -> a,
-  markupAName         :: String -> a,
-  markupPic           :: String -> a,
-  markupExample       :: [Example] -> a
-}
-
-
-data HaddockModInfo name = HaddockModInfo {
-  hmi_description :: Maybe (Doc name),
-  hmi_portability :: Maybe String,
-  hmi_stability   :: Maybe String,
-  hmi_maintainer  :: Maybe String
-}
+data DocMarkup id a = Markup
+  { markupEmpty         :: a
+  , markupString        :: String -> a
+  , markupParagraph     :: a -> a
+  , markupAppend        :: a -> a -> a
+  , markupIdentifier    :: [id] -> a
+  , markupModule        :: String -> a
+  , markupEmphasis      :: a -> a
+  , markupMonospaced    :: a -> a
+  , markupUnorderedList :: [a] -> a
+  , markupOrderedList   :: [a] -> a
+  , markupDefList       :: [(a,a)] -> a
+  , markupCodeBlock     :: a -> a
+  , markupURL           :: String -> a
+  , markupAName         :: String -> a
+  , markupPic           :: String -> a
+  , markupExample       :: [Example] -> a
+  }
+
+
+data HaddockModInfo name = HaddockModInfo
+  { hmi_description :: Maybe (Doc name)
+  , hmi_portability :: Maybe String
+  , hmi_stability   :: Maybe String
+  , hmi_maintainer  :: Maybe String
+  }
 
 
 emptyHaddockModInfo :: HaddockModInfo a
-emptyHaddockModInfo = HaddockModInfo {
-  hmi_description = Nothing,
-  hmi_portability = Nothing,
-  hmi_stability   = Nothing,
-  hmi_maintainer  = Nothing
-}
+emptyHaddockModInfo = HaddockModInfo
+  { hmi_description = Nothing
+  , hmi_portability = Nothing
+  , hmi_stability   = Nothing
+  , hmi_maintainer  = Nothing
+  }
 
 
 -----------------------------------------------------------------------------
@@ -348,21 +351,22 @@ emptyHaddockModInfo = HaddockModInfo {
 {-! for DocOption derive: Binary !-}
 -- | Source-level options for controlling the documentation.
 data DocOption
-  = OptHide           -- ^ This module should not appear in the docs
+  = 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.
+  | OptIgnoreExports   -- ^ Pretend everything is exported.
+  | OptNotHome         -- ^ Not the best place to get docs for things
+                       -- exported by this module.
   deriving (Eq, Show)
 
 
 -- | Option controlling how to qualify names
 data Qualification
-  = NoQual                      -- ^ Never qualify any names
-  | FullQual                    -- ^ Qualify all names fully
-  | LocalQual (Maybe Module)    -- ^ Qualify all imported names fully
-  | RelativeQual (Maybe Module) -- ^ Like local, but strip module prefix
-                                --   from modules in the same hierarchy
+  = NoQual                       -- ^ Never qualify any names.
+  | FullQual                     -- ^ Qualify all names fully.
+  | LocalQual (Maybe Module)     -- ^ Qualify all imported names fully.
+  | RelativeQual (Maybe Module)  -- ^ Like local, but strip module prefix.
+                                 --   from modules in the same hierarchy.
+
 
 -----------------------------------------------------------------------------
 -- * Error handling
@@ -395,7 +399,7 @@ tell w = Writer ((), w)
 -- Exceptions
 
 
--- | Haddock's own exception type
+-- | Haddock's own exception type.
 data HaddockException = HaddockException String deriving Typeable