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

Portability | portable
Stability | experimental
Maintainer | haddock@projects.haskellorg

Documentation.Haddock

Contents

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

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 :: !(Maybe (Doc Name))
  - ifaceRnDoc :: Maybe (Doc DocName)
  - ifaceOptions :: ![DocOption]
  - ifaceDeclMap :: Map Name DeclInfo
  - ifaceRnDocMap :: Map Name (DocForDecl DocName)
  - ifaceSubMap :: Map Name [Name]
  - ifaceExportItems :: ![ExportItem Name]
  - ifaceRnExportItems :: [ExportItem DocName]
  - ifaceExports :: ![Name]
  - ifaceVisibleExports :: ![Name]
  - ifaceInstances :: ![Instance]
  - ifaceInstanceDocMap :: Map Name (Doc Name)
  - ifaceHaddockCoverage :: (Int, Int)
  }
- data InstalledInterface = InstalledInterface {
  - instMod :: Module
  - instInfo :: HaddockModInfo Name
  - instDocMap :: Map Name (DocForDecl Name)
  - instExports :: [Name]
  - instVisibleExports :: [Name]
  - instOptions :: [DocOption]
  - instSubMap :: Map Name [Name]
  }
- 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]
    }
  - | ExportNoDecl {
    - expItemName :: name
    - expItemSubs :: [name]
    }
  - | ExportGroup {
    - expItemSectionLevel :: Int
    - expItemSectionId :: String
    - expItemSectionText :: Doc name
    }
  - | ExportDoc (Doc name)
  - | ExportModule Module
- type Decl = LHsDecl Name
- type DeclInfo = (Decl, DocForDecl Name, [(Name, DocForDecl Name)])
- type DocForDecl name = (Maybe (Doc 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 = ([HsPred name], name, [HsType name])
- data Doc id
  - = DocEmpty
  - | DocAppend (Doc id) (Doc id)
  - | DocString String
  - | DocParagraph (Doc id)
  - | DocIdentifier [id]
  - | DocModule String
  - | DocEmphasis (Doc id)
  - | DocMonospaced (Doc id)
  - | DocUnorderedList [Doc id]
  - | DocOrderedList [Doc id]
  - | DocDefList [(Doc id, Doc id)]
  - | DocCodeBlock (Doc id)
  - | DocURL String
  - | DocPic String
  - | DocAName String
  - | DocExamples [Example]
- data Example = Example {
  - exampleExpression :: String
  - exampleResult :: [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
  }
- markup :: DocMarkup id a -> Doc id -> a
- data InterfaceFile = InterfaceFile {
  - ifLinkEnv :: LinkEnv
  - ifInstalledIfaces :: [InstalledInterface]
  }
- readInterfaceFile :: 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_WikiBaseURL String
  - | Flag_WikiModuleURL String
  - | Flag_WikiEntityURL String
  - | Flag_LaTeX
  - | Flag_LaTeXStyle String
  - | Flag_Help
  - | Flag_Verbosity String
  - | Flag_Version
  - | Flag_UseContents String
  - | Flag_GenContents
  - | Flag_UseIndex String
  - | Flag_GenIndex
  - | Flag_IgnoreAllExports
  - | Flag_HideModule String
  - | Flag_OptGhc String
  - | Flag_GhcLibDir String
  - | Flag_GhcVersion
  - | Flag_PrintGhcLibDir
  - | Flag_NoWarnings
  - | Flag_UseUnicode
  - | Flag_NoTmpCompDir
  - | Flag_Qualification String
  - | Flag_PrettyHtml
- data DocOption
  - = OptHide
  - | OptPrune
  - | OptIgnoreExports
  - | OptNotHome

# 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 :: !(Maybe (Doc Name))

  Documentation header.

ifaceRnDoc :: Maybe (Doc DocName)

  Documentation header with cross-reference information.

ifaceOptions :: ![DocOption]

  Haddock options for this module (prune, ignore-exports, etc).

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.

ifaceRnDocMap :: Map Name (DocForDecl DocName)

  Documentation of declarations originating from the module (including subordinates).

ifaceSubMap :: Map Name [Name]
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.

ifaceInstances :: ![Instance]

  Instances exported by the module.

ifaceInstanceDocMap :: Map Name (Doc Name)

  Documentation of instances defined in the module.

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.

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 :: Map Name (DocForDecl Name)

  Documentation of declarations originating from the module (including subordinates).

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]

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.

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 Decl = LHsDecl Name

type DeclInfo = (Decl, DocForDecl Name, [(Name, DocForDecl Name)])

A declaration that may have documentation, including its subordinates, which may also have documentation.

type DocForDecl name = (Maybe (Doc 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 = ([HsPred name], name, [HsType name])

The head of an instance. Consists of a context, a class name and a list of instance types.

# Documentation comments

data Doc id

Constructors

DocEmpty |
DocAppend (Doc id) (Doc id) |
DocString String |
DocParagraph (Doc id) |
DocIdentifier [id] |
DocModule String |
DocEmphasis (Doc id) |
DocMonospaced (Doc id) |
DocUnorderedList [Doc id] |
DocOrderedList [Doc id] |
DocDefList [(Doc id, Doc id)] |
DocCodeBlock (Doc id) |
DocURL String |
DocPic String |
DocAName String |
DocExamples [Example] |

Instances

Functor Doc |
Eq id => Eq (Doc id) |
Show id => Show (Doc id) |
Binary id => Binary (Doc id) |

data Example

Constructors

Example |

Fields

exampleExpression :: String
exampleResult :: [String]

Instances

Eq Example |
Show Example |
Binary Example |

data DocMarkup id a

Constructors

Markup |

Fields

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

Constructors

HaddockModInfo |

Fields

hmi_description :: Maybe (Doc name)
hmi_portability :: Maybe String
hmi_stability :: Maybe String
hmi_maintainer :: Maybe String

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 :: 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_WikiBaseURL String |
Flag_WikiModuleURL String |
Flag_WikiEntityURL String |
Flag_LaTeX |
Flag_LaTeXStyle String |
Flag_Help |
Flag_Verbosity String |
Flag_Version |
Flag_UseContents String |
Flag_GenContents |
Flag_UseIndex String |
Flag_GenIndex |
Flag_IgnoreAllExports |
Flag_HideModule String |
Flag_OptGhc String |
Flag_GhcLibDir String |
Flag_GhcVersion |
Flag_PrintGhcLibDir |
Flag_NoWarnings |
Flag_UseUnicode |
Flag_NoTmpCompDir |
Flag_Qualification String |
Flag_PrettyHtml |

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.

Instances

Eq DocOption |
Show DocOption |
Binary DocOption |