Documentation.Haddock

haddock-2.14.3: A documentation-generation tool for Haskell libraries

Copyright | (c) David Waern 2010
License | BSD-like
Maintainer | haddock@projects.haskellorg
Stability | experimental
Portability | portable
Safe Haskell | None
Language | Haskell2010

Documentation.Haddock

Contents

- Interface
- Export items & declarations
- Cross-referencing
- Instances
- Documentation comments
- Interface files
- Flags and options
- Program entry point

Description

The Haddock API: A rudimentory, highly experimental API exposing some of the internals of Haddock. Don't expect it to be stable.

Synopsis

- data Interface = Interface {
  - ifaceMod :: !Module
  - ifaceOrigFilename :: !FilePath
  - ifaceInfo :: !(HaddockModInfo Name)
  - ifaceDoc :: !(Documentation Name)
  - ifaceRnDoc :: !(Documentation DocName)
  - ifaceOptions :: ![DocOption]
  - ifaceDeclMap :: !(Map Name [LHsDecl Name])
  - ifaceDocMap :: !(DocMap Name)
  - ifaceArgMap :: !(ArgMap Name)
  - ifaceRnDocMap :: !(DocMap DocName)
  - ifaceRnArgMap :: !(ArgMap DocName)
  - ifaceSubMap :: !(Map Name [Name])
  - ifaceFixMap :: !(Map Name Fixity)
  - ifaceExportItems :: ![ExportItem Name]
  - ifaceRnExportItems :: ![ExportItem DocName]
  - ifaceExports :: ![Name]
  - ifaceVisibleExports :: ![Name]
  - ifaceModuleAliases :: !AliasMap
  - ifaceInstances :: ![ClsInst]
  - ifaceFamInstances :: ![FamInst]
  - ifaceHaddockCoverage :: !(Int, Int)
  - ifaceWarningMap :: !WarningMap
  }
- data InstalledInterface = InstalledInterface {
  - instMod :: Module
  - instInfo :: HaddockModInfo Name
  - instDocMap :: DocMap Name
  - instArgMap :: ArgMap Name
  - instExports :: [Name]
  - instVisibleExports :: [Name]
  - instOptions :: [DocOption]
  - instSubMap :: Map Name [Name]
  - instFixMap :: Map Name Fixity
  }
- createInterfaces :: [Flag] -> [String] -> IO [Interface]
- processModules :: Verbosity -> [String] -> [Flag] -> [InterfaceFile] -> Ghc ([Interface], LinkEnv)
- data ExportItem name
  - = ExportDecl {
    - expItemDecl :: !(LHsDecl name)
    - expItemMbDoc :: !(DocForDecl name)
    - expItemSubDocs :: ![(name, DocForDecl name)]
    - expItemInstances :: ![DocInstance name]
    - expItemFixities :: ![(name, Fixity)]
    - expItemSpliced :: !Bool
    }
  - | ExportNoDecl {
    - expItemName :: !name
    - expItemSubs :: ![name]
    }
  - | ExportGroup {
    - expItemSectionLevel :: !Int
    - expItemSectionId :: !String
    - expItemSectionText :: !(Doc name)
    }
  - | ExportDoc !(Doc name)
  - | ExportModule !Module
- type DocForDecl name = (Documentation name, FnArgsDoc name)
- type FnArgsDoc name = Map Int (Doc name)
- type LinkEnv = Map Name Module
- data DocName
  - = Documented Name Module
  - | Undocumented Name
- type DocInstance name = (InstHead name, Maybe (Doc name))
- type InstHead name = (name, [HsType name], [HsType name], InstType name)
- data Doc id
  - = DocEmpty
  - | DocAppend (Doc id) (Doc id)
  - | DocString String
  - | DocParagraph (Doc id)
  - | DocIdentifier id
  - | DocIdentifierUnchecked (ModuleName, OccName)
  - | DocModule String
  - | DocWarning (Doc id)
  - | DocEmphasis (Doc id)
  - | DocMonospaced (Doc id)
  - | DocBold (Doc id)
  - | DocUnorderedList [Doc id]
  - | DocOrderedList [Doc id]
  - | DocDefList [(Doc id, Doc id)]
  - | DocCodeBlock (Doc id)
  - | DocHyperlink Hyperlink
  - | DocPic Picture
  - | DocAName String
  - | DocProperty String
  - | DocExamples [Example]
  - | DocHeader (Header (Doc id))
- data Example = Example {
  - exampleExpression :: String
  - exampleResult :: [String]
  }
- data Hyperlink = Hyperlink {
  - hyperlinkUrl :: String
  - hyperlinkLabel :: Maybe String
  }
- data DocMarkup id a = Markup {
  - markupEmpty :: a
  - markupString :: String -> a
  - markupParagraph :: a -> a
  - markupAppend :: a -> a -> a
  - markupIdentifier :: id -> a
  - markupIdentifierUnchecked :: (ModuleName, OccName) -> a
  - markupModule :: String -> a
  - markupWarning :: a -> a
  - markupEmphasis :: a -> a
  - markupBold :: a -> a
  - markupMonospaced :: a -> a
  - markupUnorderedList :: [a] -> a
  - markupOrderedList :: [a] -> a
  - markupDefList :: [(a, a)] -> a
  - markupCodeBlock :: a -> a
  - markupHyperlink :: Hyperlink -> a
  - markupAName :: String -> a
  - markupPic :: Picture -> a
  - markupProperty :: String -> a
  - markupExample :: [Example] -> a
  - markupHeader :: Header a -> a
  }
- data Documentation name = Documentation {
  - documentationDoc :: Maybe (Doc name)
  - documentationWarning :: !(Maybe (Doc name))
  }
- type ArgMap a = Map Name (Map Int (Doc a))
- type AliasMap = Map Module ModuleName
- type WarningMap = DocMap Name
- type DocMap a = Map Name (Doc a)
- data HaddockModInfo name = HaddockModInfo {
  - hmi_description :: Maybe (Doc name)
  - hmi_copyright :: Maybe String
  - hmi_license :: Maybe String
  - hmi_maintainer :: Maybe String
  - hmi_stability :: Maybe String
  - hmi_portability :: Maybe String
  - hmi_safety :: Maybe String
  - hmi_language :: Maybe Language
  - hmi_extensions :: [ExtensionFlag]
  }
- markup :: DocMarkup id a -> Doc id -> a
- data InterfaceFile = InterfaceFile {
  - ifLinkEnv :: LinkEnv
  - ifInstalledIfaces :: [InstalledInterface]
  }
- readInterfaceFile :: forall m. MonadIO m => NameCacheAccessor m -> FilePath -> m (Either String InterfaceFile)
- nameCacheFromGhc :: NameCacheAccessor Ghc
- freshNameCache :: NameCacheAccessor IO
- type NameCacheAccessor m = (m NameCache, NameCache -> m ())
- data Flag
  - = Flag_BuiltInThemes
  - | Flag_CSS String
  - | Flag_ReadInterface String
  - | Flag_DumpInterface String
  - | Flag_Heading String
  - | Flag_Html
  - | Flag_Hoogle
  - | Flag_Lib String
  - | Flag_OutputDir FilePath
  - | Flag_Prologue FilePath
  - | Flag_SourceBaseURL String
  - | Flag_SourceModuleURL String
  - | Flag_SourceEntityURL String
  - | Flag_SourceLEntityURL String
  - | Flag_WikiBaseURL String
  - | Flag_WikiModuleURL String
  - | Flag_WikiEntityURL String
  - | Flag_LaTeX
  - | Flag_LaTeXStyle String
  - | Flag_Help
  - | Flag_Verbosity String
  - | Flag_Version
  - | Flag_CompatibleInterfaceVersions
  - | Flag_InterfaceVersion
  - | Flag_UseContents String
  - | Flag_GenContents
  - | Flag_UseIndex String
  - | Flag_GenIndex
  - | Flag_IgnoreAllExports
  - | Flag_HideModule String
  - | Flag_ShowExtensions String
  - | Flag_OptGhc String
  - | Flag_GhcLibDir String
  - | Flag_GhcVersion
  - | Flag_PrintGhcPath
  - | Flag_PrintGhcLibDir
  - | Flag_NoWarnings
  - | Flag_UseUnicode
  - | Flag_NoTmpCompDir
  - | Flag_Qualification String
  - | Flag_PrettyHtml
  - | Flag_PrintMissingDocs
- data DocOption
  - = OptHide
  - | OptPrune
  - | OptIgnoreExports
  - | OptNotHome
  - | OptShowExtensions
- haddock :: [String] -> IO ()

# Interface

data Interface

`Interface` holds all information used to render a single Haddock page. It represents the interface of a module. The core business of Haddock 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.

Constructors

Interface |
Fields ifaceMod :: !Module The module behind this interface. ifaceOrigFilename :: !FilePath Original file name of the module. ifaceInfo :: !(HaddockModInfo Name) Textual information about the module. ifaceDoc :: !(Documentation Name) Documentation header. ifaceRnDoc :: !(Documentation DocName) Documentation header with cross-reference information. ifaceOptions :: ![DocOption] Haddock options for this module (prune, ignore-exports, etc). ifaceDeclMap :: !(Map Name [LHsDecl Name]) 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. ifaceDocMap :: !(DocMap Name) Documentation of declarations originating from the module (including subordinates). ifaceArgMap :: !(ArgMap Name) ifaceRnDocMap :: !(DocMap DocName) Documentation of declarations originating from the module (including subordinates). ifaceRnArgMap :: !(ArgMap DocName) ifaceSubMap :: !(Map Name [Name]) ifaceFixMap :: !(Map Name Fixity) ifaceExportItems :: ![ExportItem Name] ifaceRnExportItems :: ![ExportItem DocName] ifaceExports :: ![Name] All names exported by 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. ifaceModuleAliases :: !AliasMap Aliases of module imports as in `import A.B.C as C`. ifaceInstances :: ![ClsInst] Instances exported by the module. ifaceFamInstances :: ![FamInst] 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. ifaceWarningMap :: !WarningMap Warnings for things defined in this module.

data InstalledInterface

A subset of the fields of `Interface` that we store in the interface files.

Constructors

InstalledInterface |
Fields instMod :: Module The module represented by this interface. instInfo :: HaddockModInfo Name Textual information about the module. instDocMap :: DocMap Name Documentation of declarations originating from the module (including subordinates). instArgMap :: ArgMap Name instExports :: [Name] All names exported by this 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. instOptions :: [DocOption] Haddock options for this module (prune, ignore-exports, etc). instSubMap :: Map Name [Name] instFixMap :: Map Name Fixity

Instances

Binary InstalledInterface |

createInterfaces

Arguments

:: [Flag] | A list of command-line flags
-> [String] | File or module names
-> IO [Interface] | Resulting list of interfaces

Create `Interface` structures from a given list of Haddock command-line flags and file or module names (as accepted by `haddock` executable). Flags that control documentation generation or show help or version information are ignored.

processModules

Arguments

:: Verbosity | Verbosity of logging to `stdout`
-> [String] | A list of file or module names sorted by module topology
-> [Flag] | Command-line flags
-> [InterfaceFile] | Interface files of package dependencies
-> Ghc ([Interface], LinkEnv) | Resulting list of interfaces and renaming environment

Create `Interface`s and a link environment by typechecking the list of modules using the GHC API and processing the resulting syntax trees.

# Export items & declarations

data ExportItem name

Constructors

ExportDecl | An exported declaration.
Fields expItemDecl :: !(LHsDecl name) A declaration. expItemMbDoc :: !(DocForDecl name) Maybe a doc comment, and possibly docs for arguments (if this decl is a function or type-synonym). expItemSubDocs :: ![(name, DocForDecl name)] Subordinate names, possibly with documentation. expItemInstances :: ![DocInstance name] Instances relevant to this declaration, possibly with documentation. expItemFixities :: ![(name, Fixity)] Fixity decls relevant to this declaration (including subordinates). expItemSpliced :: !Bool Whether the ExportItem is from a TH splice or not, for generating the appropriate type of Source link.
ExportNoDecl | An exported entity for which we have no documentation (perhaps because it resides in another package).
Fields expItemName :: !name expItemSubs :: ![name] Subordinate names.
ExportGroup | A section heading.
Fields expItemSectionLevel :: !Int Section level (1, 2, 3, ...). expItemSectionId :: !String Section id (for hyperlinks). expItemSectionText :: !(Doc name) Section heading text.
ExportDoc !(Doc name) | Some documentation.
ExportModule !Module | A cross-reference to another module.

type DocForDecl name = (Documentation name, FnArgsDoc name)

type FnArgsDoc name = Map Int (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.

# Cross-referencing

type LinkEnv = Map Name Module

Type of environment used to cross-reference identifiers in the syntax.

data DocName

Extends `Name` with cross-reference information.

Constructors

Documented Name Module | This thing is part of the (existing or resulting) documentation. The `Module` is the preferred place in the documentation to refer to.
Undocumented Name | This thing is not part of the (existing or resulting) documentation, as far as Haddock knows.

Instances

Eq DocName |
NamedThing DocName |
Binary DocName |

# Instances

type DocInstance name = (InstHead name, Maybe (Doc name))

An instance head that may have documentation.

type InstHead name = (name, [HsType name], [HsType name], InstType name)

The head of an instance. Consists of a class name, a list of kind parameters, a list of type parameters and an instance type

# Documentation comments

data Doc id

Constructors

DocEmpty |
DocAppend (Doc id) (Doc id) |
DocString String |
DocParagraph (Doc id) |
DocIdentifier id |
DocIdentifierUnchecked (ModuleName, OccName) |
DocModule String |
DocWarning (Doc id) |
DocEmphasis (Doc id) |
DocMonospaced (Doc id) |
DocBold (Doc id) |
DocUnorderedList [Doc id] |
DocOrderedList [Doc id] |
DocDefList [(Doc id, Doc id)] |
DocCodeBlock (Doc id) |
DocHyperlink Hyperlink |
DocPic Picture |
DocAName String |
DocProperty String |
DocExamples [Example] |
DocHeader (Header (Doc id)) |

Instances

Functor Doc |
Foldable Doc |
Traversable Doc |
Monoid (Doc id) |
NFData a => NFData (Doc a) |
Binary id => Binary (Doc id) |

data Example

Constructors

Example |
Fields exampleExpression :: String exampleResult :: [String]

Instances

Eq Example |
Show Example |
NFData Example |
Binary Example |

data Hyperlink

Constructors

Hyperlink |
Fields hyperlinkUrl :: String hyperlinkLabel :: Maybe String

Instances

Eq Hyperlink |
Show Hyperlink |
NFData Hyperlink |
Binary Hyperlink |

data DocMarkup id a

Constructors

Markup |
Fields markupEmpty :: a markupString :: String -> a markupParagraph :: a -> a markupAppend :: a -> a -> a markupIdentifier :: id -> a markupIdentifierUnchecked :: (ModuleName, OccName) -> a markupModule :: String -> a markupWarning :: a -> a markupEmphasis :: a -> a markupBold :: a -> a markupMonospaced :: a -> a markupUnorderedList :: [a] -> a markupOrderedList :: [a] -> a markupDefList :: [(a, a)] -> a markupCodeBlock :: a -> a markupHyperlink :: Hyperlink -> a markupAName :: String -> a markupPic :: Picture -> a markupProperty :: String -> a markupExample :: [Example] -> a markupHeader :: Header a -> a

data Documentation name

Constructors

Documentation |
Fields documentationDoc :: Maybe (Doc name) documentationWarning :: !(Maybe (Doc name))

Instances

Functor Documentation |

type ArgMap a = Map Name (Map Int (Doc a))

type AliasMap = Map Module ModuleName

type WarningMap = DocMap Name

type DocMap a = Map Name (Doc a)

data HaddockModInfo name

Constructors

HaddockModInfo |
Fields hmi_description :: Maybe (Doc name) hmi_copyright :: Maybe String hmi_license :: Maybe String hmi_maintainer :: Maybe String hmi_stability :: Maybe String hmi_portability :: Maybe String hmi_safety :: Maybe String hmi_language :: Maybe Language hmi_extensions :: [ExtensionFlag]

Instances

Binary name => Binary (HaddockModInfo name) |

markup :: DocMarkup id a -> Doc id -> a

# Interface files

data InterfaceFile

Constructors

InterfaceFile |
Fields ifLinkEnv :: LinkEnv ifInstalledIfaces :: [InstalledInterface]

Instances

Binary InterfaceFile |

readInterfaceFile :: forall m. MonadIO m => NameCacheAccessor m -> FilePath -> m (Either String InterfaceFile)

Read a Haddock (`.haddock`) interface file. Return either an `InterfaceFile` or an error message.

This function can be called in two ways. Within a GHC session it will update the use and update the session's name cache. Outside a GHC session a new empty name cache is used. The function is therefore generic in the monad being used. The exact monad is whichever monad the first argument, the getter and setter of the name cache, requires.

nameCacheFromGhc :: NameCacheAccessor Ghc

freshNameCache :: NameCacheAccessor IO

type NameCacheAccessor m = (m NameCache, NameCache -> m ())

# Flags and options

data Flag

Constructors

Flag_BuiltInThemes |
Flag_CSS String |
Flag_ReadInterface String |
Flag_DumpInterface String |
Flag_Heading String |
Flag_Html |
Flag_Hoogle |
Flag_Lib String |
Flag_OutputDir FilePath |
Flag_Prologue FilePath |
Flag_SourceBaseURL String |
Flag_SourceModuleURL String |
Flag_SourceEntityURL String |
Flag_SourceLEntityURL String |
Flag_WikiBaseURL String |
Flag_WikiModuleURL String |
Flag_WikiEntityURL String |
Flag_LaTeX |
Flag_LaTeXStyle String |
Flag_Help |
Flag_Verbosity String |
Flag_Version |
Flag_CompatibleInterfaceVersions |
Flag_InterfaceVersion |
Flag_UseContents String |
Flag_GenContents |
Flag_UseIndex String |
Flag_GenIndex |
Flag_IgnoreAllExports |
Flag_HideModule String |
Flag_ShowExtensions String |
Flag_OptGhc String |
Flag_GhcLibDir String |
Flag_GhcVersion |
Flag_PrintGhcPath |
Flag_PrintGhcLibDir |
Flag_NoWarnings |
Flag_UseUnicode |
Flag_NoTmpCompDir |
Flag_Qualification String |
Flag_PrettyHtml |
Flag_PrintMissingDocs |

Instances

Eq Flag |

data DocOption

Source-level options for controlling the documentation.

Constructors

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.
OptShowExtensions | Render enabled extensions for this module.

Instances

Eq DocOption |
Show DocOption |
Binary DocOption |

# Program entry point

haddock :: [String] -> IO ()

Run Haddock with given list of arguments.

Haddock's own main function is defined in terms of this:

    main = getArgs >>= haddock