From 77cc272c24d5ba1819be7155b45697de1f906a89 Mon Sep 17 00:00:00 2001
From: David Waern <david.waern@gmail.com>
Date: Sat, 20 Nov 2010 19:42:51 +0000
Subject: Follow the style guide closer in Haddock.Types and improve docs
---
src/Haddock/Types.hs | 290 ++++++++++++++++++++++++++-------------------------
1 file 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
--
cgit v1.2.3