Documentation.Haddock

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

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]
• ifaceOrphanInstances :: ![DocInstance Name]

  Orphan instances

• ifaceRnOrphanInstances :: ![DocInstance DocName]
• 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.

• ifaceTokenizedSrc :: !(Maybe [RichToken])

  Tokenized source code of module (avaliable if Haddock is invoked with source generation flag).

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

toInstalledIface :: Interface -> InstalledInterface

Convert an Interface to an 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 Interfaces 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 !(MDoc name)

Some documentation.

ExportModule !Module

A cross-reference to another module.

type DocForDecl name = (Documentation name, FnArgsDoc name)

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

Methods

(==) :: DocName -> DocName -> Bool

(/=) :: DocName -> DocName -> Bool

Data DocName

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> DocName -> c DocName

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c DocName

toConstr :: DocName -> Constr

dataTypeOf :: DocName -> DataType

dataCast1 :: Typeable (* -> *) t => (forall d. Data d => c (t d)) -> Maybe (c DocName)

dataCast2 :: Typeable (* -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c DocName)

gmapT :: (forall b. Data b => b -> b) -> DocName -> DocName

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> DocName -> r

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> DocName -> r

gmapQ :: (forall d. Data d => d -> u) -> DocName -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> DocName -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> DocName -> m DocName

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> DocName -> m DocName

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> DocName -> m DocName

NamedThing DocName

Methods

getOccName :: DocName -> OccName

getName :: DocName -> Name

Outputable DocName

Useful for debugging

Methods

ppr :: DocName -> SDoc

pprPrec :: Rational -> DocName -> SDoc

OutputableBndr DocName

Methods

pprBndr :: BindingSite -> DocName -> SDoc

pprPrefixOcc :: DocName -> SDoc

pprInfixOcc :: DocName -> SDoc

type PostTc DocName Type

type PostTc DocName Type = PlaceHolder

type PostTc DocName Type

type PostTc DocName Type = PlaceHolder

type PostTc DocName Coercion

type PostTc DocName Coercion = PlaceHolder

type PostTc DocName Coercion

type PostTc DocName Coercion = PlaceHolder

type PostTc DocName Kind

type PostTc DocName Kind = PlaceHolder

type PostTc DocName Kind

type PostTc DocName Kind = PlaceHolder

type PostRn DocName Bool

type PostRn DocName Bool = PlaceHolder

type PostRn DocName Bool

type PostRn DocName Bool = PlaceHolder

type PostRn DocName NameSet

type PostRn DocName NameSet = PlaceHolder

type PostRn DocName NameSet

type PostRn DocName NameSet = PlaceHolder

type PostRn DocName Fixity

type PostRn DocName Fixity = PlaceHolder

type PostRn DocName Fixity

type PostRn DocName Fixity = PlaceHolder

type PostRn DocName Name

type PostRn DocName Name = DocName

type PostRn DocName DocName

type PostRn DocName DocName = DocName

type PostRn DocName [Name]

type PostRn DocName [Name] = PlaceHolder

type PostRn DocName [Name]

type PostRn DocName [Name] = PlaceHolder

type PostRn DocName (Located Name)

type PostRn DocName (Located Name) = Located DocName

Instances

type DocInstance name = (InstHead name, Maybe (MDoc name), Located name)

An instance head that may have documentation and a source location.

data InstHead 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

type Doc id = DocH (ModuleName, OccName) id

type MDoc id = MetaDoc (ModuleName, OccName) id

data DocH mod id :: * -> * -> *

Constructors

DocEmpty

DocAppend (DocH mod id) (DocH mod id)

DocString String

DocParagraph (DocH mod id)

DocIdentifier id

DocIdentifierUnchecked mod

DocModule String

DocWarning (DocH mod id)

DocEmphasis (DocH mod id)

DocMonospaced (DocH mod id)

DocBold (DocH mod id)

DocUnorderedList [DocH mod id]

DocOrderedList [DocH mod id]

DocDefList [(DocH mod id, DocH mod id)]

DocCodeBlock (DocH mod id)

DocHyperlink Hyperlink

DocPic Picture

DocMathInline String

DocMathDisplay String

DocAName String

DocProperty String

DocExamples [Example]

DocHeader (Header (DocH mod id))

Instances

Functor (DocH mod)

Methods

fmap :: (a -> b) -> DocH mod a -> DocH mod b

(<$) :: a -> DocH mod b -> DocH mod a

Foldable (DocH mod)

Methods

fold :: Monoid m => DocH mod m -> m

foldMap :: Monoid m => (a -> m) -> DocH mod a -> m

foldr :: (a -> b -> b) -> b -> DocH mod a -> b

foldr' :: (a -> b -> b) -> b -> DocH mod a -> b

foldl :: (b -> a -> b) -> b -> DocH mod a -> b

foldl' :: (b -> a -> b) -> b -> DocH mod a -> b

foldr1 :: (a -> a -> a) -> DocH mod a -> a

foldl1 :: (a -> a -> a) -> DocH mod a -> a

toList :: DocH mod a -> [a]

null :: DocH mod a -> Bool

length :: DocH mod a -> Int

elem :: Eq a => a -> DocH mod a -> Bool

maximum :: Ord a => DocH mod a -> a

minimum :: Ord a => DocH mod a -> a

sum :: Num a => DocH mod a -> a

product :: Num a => DocH mod a -> a

Traversable (DocH mod)

Methods

traverse :: Applicative f => (a -> f b) -> DocH mod a -> f (DocH mod b)

sequenceA :: Applicative f => DocH mod (f a) -> f (DocH mod a)

mapM :: Monad m => (a -> m b) -> DocH mod a -> m (DocH mod b)

sequence :: Monad m => DocH mod (m a) -> m (DocH mod a)

(Eq id, Eq mod) => Eq (DocH mod id)

Methods

(==) :: DocH mod id -> DocH mod id -> Bool

(/=) :: DocH mod id -> DocH mod id -> Bool

(Show id, Show mod) => Show (DocH mod id)

Methods

showsPrec :: Int -> DocH mod id -> ShowS

show :: DocH mod id -> String

showList :: [DocH mod id] -> ShowS

data Example :: *

Constructors

Example

Fields

• exampleExpression :: String
• exampleResult :: [String]

Instances

Eq Example

Methods

(==) :: Example -> Example -> Bool

(/=) :: Example -> Example -> Bool

Show Example

Methods

showsPrec :: Int -> Example -> ShowS

show :: Example -> String

showList :: [Example] -> ShowS

data Hyperlink :: *

Constructors

Hyperlink

Fields

• hyperlinkUrl :: String
• hyperlinkLabel :: Maybe String

Instances

Eq Hyperlink

Methods

(==) :: Hyperlink -> Hyperlink -> Bool

(/=) :: Hyperlink -> Hyperlink -> Bool

Show Hyperlink

Methods

showsPrec :: Int -> Hyperlink -> ShowS

show :: Hyperlink -> String

showList :: [Hyperlink] -> ShowS

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
• markupMathInline :: String -> a
• markupMathDisplay :: String -> a
• markupProperty :: String -> a
• markupExample :: [Example] -> a
• markupHeader :: Header a -> a

data Documentation name

Constructors

Documentation

Fields

• documentationDoc :: Maybe (MDoc name)
• documentationWarning :: !(Maybe (Doc name))

Instances

Functor Documentation

Methods

fmap :: (a -> b) -> Documentation a -> Documentation b

(<$) :: a -> Documentation b -> Documentation a

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

type AliasMap = Map Module ModuleName

type WarningMap = Map Name (Doc Name)

type DocMap a = Map Name (MDoc 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 :: [Extension]

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

Interface files

data InterfaceFile

Constructors

InterfaceFile

Fields

• ifLinkEnv :: LinkEnv
• ifInstalledIfaces :: [InstalledInterface]

Instances

Binary InterfaceFile

Methods

put_ :: BinHandle -> InterfaceFile -> IO ()

put :: BinHandle -> InterfaceFile -> IO (Bin InterfaceFile)

get :: BinHandle -> IO 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_HyperlinkedSource

Flag_SourceCss String

Flag_Mathjax 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_NoPrintMissingDocs

Flag_PackageName String

Flag_PackageVersion String

Instances

Eq Flag

Methods

(==) :: Flag -> Flag -> Bool

(/=) :: Flag -> Flag -> Bool

Show Flag

Methods

showsPrec :: Int -> Flag -> ShowS

show :: Flag -> String

showList :: [Flag] -> ShowS

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

Methods

(==) :: DocOption -> DocOption -> Bool

(/=) :: DocOption -> DocOption -> Bool

Show DocOption

Methods

showsPrec :: Int -> DocOption -> ShowS

show :: DocOption -> String

showList :: [DocOption] -> ShowS

Error handling

data HaddockException

Haddock's own exception type.

Constructors

HaddockException String

Instances

Show HaddockException

Methods

showsPrec :: Int -> HaddockException -> ShowS

show :: HaddockException -> String

showList :: [HaddockException] -> ShowS

Exception HaddockException

Methods

toException :: HaddockException -> SomeException

fromException :: SomeException -> Maybe HaddockException

displayException :: HaddockException -> String

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

haddockWithGhc :: (forall a. [Flag] -> Ghc a -> IO a) -> [String] -> IO ()

getGhcDirs :: [Flag] -> IO (String, String)

withGhc :: [Flag] -> Ghc a -> IO a