W3cubDocs

/Haskell 9

Documentation.Haddock

Copyright (c) David Waern 2010
License BSD-like
Maintainer [email protected]
Stability experimental
Portability portable
Safe Haskell None
Language Haskell2010

Description

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

Interface

data Interface Source

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

data InstalledInterface Source

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

Constructors

InstalledInterface

Fields

toInstalledIface :: Interface -> InstalledInterface Source

Convert an Interface to an InstalledInterface

createInterfaces Source

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 Source

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 Source

Constructors

ExportDecl (XExportDecl name)

An exported declaration.

ExportNoDecl

An exported entity for which we have no documentation (perhaps because it resides in another package).

Fields

ExportGroup

A section heading.

Fields

ExportDoc !(MDoc (IdP name))

Some documentation.

ExportModule !Module

A cross-reference to another module.

type DocForDecl name = (Documentation name, FnArgsDoc name) Source

type FnArgsDoc name = Map Int (MDoc name) Source

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 Source

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

data DocName Source

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
Instances details
NamedThing DocName Source
Instance details

Defined in Haddock.Types

HasOccName DocName Source
Instance details

Defined in Haddock.Types

Methods

occName :: DocName -> OccName Source

Binary DocName Source
Instance details

Defined in Haddock.InterfaceFile

Outputable DocName Source

Useful for debugging

Instance details

Defined in Haddock.Types

Methods

ppr :: DocName -> SDoc Source

OutputableBndr DocName Source
Instance details

Defined in Haddock.Types

Data DocName Source
Instance details

Defined in Haddock.Types

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 :: forall r r'. (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

Eq DocName Source
Instance details

Defined in Haddock.Types

Methods

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

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

type Anno DocName Source
Instance details

Defined in Haddock.Types

Instances

type DocInstance name = (InstHead name, Maybe (MDoc (IdP name)), Located (IdP name), Maybe Module) Source

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

data InstHead name Source

The head of an instance. Consists of a class name, a list of type parameters (which may be annotated with kinds), and an instance type

Documentation comments

type Doc id = DocH (Wrap (ModuleName, OccName)) (Wrap id) Source

type MDoc id = MetaDoc (Wrap (ModuleName, OccName)) (Wrap id) Source

data DocH mod id Source

Constructors

DocEmpty
DocAppend (DocH mod id) (DocH mod id)
DocString String
DocParagraph (DocH mod id)
DocIdentifier id
DocIdentifierUnchecked mod

A qualified identifier that couldn't be resolved.

DocModule (ModLink (DocH mod id))

A link to a module, with an optional label.

DocWarning (DocH mod id)

This constructor has no counterpart in Haddock markup.

DocEmphasis (DocH mod id)
DocMonospaced (DocH mod id)
DocBold (DocH mod id)
DocUnorderedList [DocH mod id]
DocOrderedList [(Int, DocH mod id)]
DocDefList [(DocH mod id, DocH mod id)]
DocCodeBlock (DocH mod id)
DocHyperlink (Hyperlink (DocH mod id))
DocPic Picture
DocMathInline String
DocMathDisplay String
DocAName String

A (HTML) anchor. It must not contain any spaces.

DocProperty String
DocExamples [Example]
DocHeader (Header (DocH mod id))
DocTable (Table (DocH mod id))
Instances
Instances details
Bifoldable DocH Source
Instance details

Defined in Documentation.Haddock.Types

Methods

bifold :: Monoid m => DocH m m -> m Source

bifoldMap :: Monoid m => (a -> m) -> (b -> m) -> DocH a b -> m Source

bifoldr :: (a -> c -> c) -> (b -> c -> c) -> c -> DocH a b -> c Source

bifoldl :: (c -> a -> c) -> (c -> b -> c) -> c -> DocH a b -> c Source

Bifunctor DocH Source
Instance details

Defined in Documentation.Haddock.Types

Methods

bimap :: (a -> b) -> (c -> d) -> DocH a c -> DocH b d Source

first :: (a -> b) -> DocH a c -> DocH b c Source

second :: (b -> c) -> DocH a b -> DocH a c Source

Bitraversable DocH Source
Instance details

Defined in Documentation.Haddock.Types

Methods

bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> DocH a b -> f (DocH c d) Source

Functor (DocH mod) Source
Instance details

Defined in Documentation.Haddock.Types

Methods

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

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

Foldable (DocH mod) Source
Instance details

Defined in Documentation.Haddock.Types

Methods

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

foldMap :: Monoid m => (a -> m) -> DocH mod a -> 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) Source
Instance details

Defined in Documentation.Haddock.Types

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)

(NFData a, NFData mod) => NFData (DocH mod a) Source
Instance details

Defined in Haddock.Types

Methods

rnf :: DocH mod a -> () Source

(Binary mod, Binary id) => Binary (DocH mod id) Source
Instance details

Defined in Haddock.InterfaceFile

Methods

put_ :: WriteBinHandle -> DocH mod id -> IO () Source

put :: WriteBinHandle -> DocH mod id -> IO (Bin (DocH mod id)) Source

get :: ReadBinHandle -> IO (DocH mod id) Source

(Show id, Show mod) => Show (DocH mod id) Source
Instance details

Defined in Documentation.Haddock.Types

Methods

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

show :: DocH mod id -> String

showList :: [DocH mod id] -> ShowS

(Eq id, Eq mod) => Eq (DocH mod id) Source
Instance details

Defined in Documentation.Haddock.Types

Methods

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

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

data Example Source

Constructors

Example
Instances
Instances details
NFData Example Source
Instance details

Defined in Haddock.Types

Methods

rnf :: Example -> () Source

Binary Example Source
Instance details

Defined in Haddock.InterfaceFile

Show Example Source
Instance details

Defined in Documentation.Haddock.Types

Methods

showsPrec :: Int -> Example -> ShowS

show :: Example -> String

showList :: [Example] -> ShowS

Eq Example Source
Instance details

Defined in Documentation.Haddock.Types

Methods

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

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

data Hyperlink id Source

Constructors

Hyperlink
Instances

type DocMarkup id a = DocMarkupH (Wrap (ModuleName, OccName)) id a Source

data DocMarkupH mod id a Source

DocMarkupH is a set of instructions for marking up documentation. In fact, it's really just a mapping from Doc to some other type [a], where [a] is usually the type of the output (HTML, say). Use markup to apply a DocMarkupH to a DocH.

Since: haddock-library-1.4.5

Constructors

Markup

Fields

data Documentation name Source

Constructors

Documentation
Instances
Instances details
Functor Documentation Source
Instance details

Defined in Haddock.Types

Methods

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

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

NFData name => NFData (Documentation name) Source
Instance details

Defined in Haddock.Types

Methods

rnf :: Documentation name -> () Source

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

type WarningMap = Map Name (Doc Name) Source

type DocMap a = Map Name (MDoc a) Source

data HaddockModInfo name Source

Instances
Instances details
NFData name => NFData (HaddockModInfo name) Source
Instance details

Defined in Haddock.Types

Methods

rnf :: HaddockModInfo name -> () Source

Binary name => Binary (HaddockModInfo name) Source
Instance details

Defined in Haddock.InterfaceFile

markup :: DocMarkupH mod id a -> DocH mod id -> a Source

Interface files

data InterfaceFile Source

Constructors

InterfaceFile

Fields

readInterfaceFile Source

Arguments

:: NameCache
-> FilePath
-> Bool

Disable version check. Can cause runtime crash.

-> IO (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.

freshNameCache :: IO NameCache Source

Flags and options

data Flag Source

Instances
Instances details
Show Flag Source
Instance details

Defined in Haddock.Options

Methods

showsPrec :: Int -> Flag -> ShowS

show :: Flag -> String

showList :: [Flag] -> ShowS

Eq Flag Source
Instance details

Defined in Haddock.Options

Methods

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

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

data DocOption Source

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.

OptPrintRuntimeRep

Render runtime reps for this module (see the GHC -fprint-explicit-runtime-reps flag)

Instances
Instances details
Binary DocOption Source
Instance details

Defined in Haddock.InterfaceFile

Show DocOption Source
Instance details

Defined in Haddock.Types

Eq DocOption Source
Instance details

Defined in Haddock.Types

Methods

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

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

Error handling

data HaddockException Source

Haddock's own exception type.

Program entry point

haddock :: [String] -> IO () Source

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 () Source

getGhcDirs :: [Flag] -> IO (Maybe FilePath, Maybe FilePath) Source

Find the lib directory for GHC and the path to ghc

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

© The University of Glasgow and others
Licensed under a BSD-style license (see top of the page).
https://downloads.haskell.org/~ghc/9.12.1/docs/libraries/haddock-api-2.30.0-754a/Documentation-Haddock.html