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
Error handling
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

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

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 Source #

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

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

Eq DocName Source #
Methods (==) :: DocName -> DocName -> Bool # (/=) :: DocName -> DocName -> Bool #
Data DocName Source #
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 Source #
Methods getOccName :: DocName -> OccName # getName :: DocName -> Name #
Outputable DocName Source #	Useful for debugging
Methods ppr :: DocName -> SDoc # pprPrec :: Rational -> DocName -> SDoc #
OutputableBndr DocName Source #
Methods pprBndr :: BindingSite -> DocName -> SDoc # pprPrefixOcc :: DocName -> SDoc # pprInfixOcc :: DocName -> SDoc #
type PostTc DocName Type Source #
type PostTc DocName Type = PlaceHolder
type PostTc DocName Type Source #
type PostTc DocName Type = PlaceHolder
type PostTc DocName Coercion Source #
type PostTc DocName Coercion = PlaceHolder
type PostTc DocName Coercion Source #
type PostTc DocName Coercion = PlaceHolder
type PostTc DocName Kind Source #
type PostTc DocName Kind = PlaceHolder
type PostTc DocName Kind Source #
type PostTc DocName Kind = PlaceHolder
type PostRn DocName Bool Source #
type PostRn DocName Bool = PlaceHolder
type PostRn DocName Bool Source #
type PostRn DocName Bool = PlaceHolder
type PostRn DocName NameSet Source #
type PostRn DocName NameSet = PlaceHolder
type PostRn DocName NameSet Source #
type PostRn DocName NameSet = PlaceHolder
type PostRn DocName Fixity Source #
type PostRn DocName Fixity = PlaceHolder
type PostRn DocName Fixity Source #
type PostRn DocName Fixity = PlaceHolder
type PostRn DocName Name Source #
type PostRn DocName Name = DocName
type PostRn DocName DocName Source #
type PostRn DocName DocName = DocName
type PostRn DocName [Name] Source #
type PostRn DocName [Name] = PlaceHolder
type PostRn DocName [Name] Source #
type PostRn DocName [Name] = PlaceHolder
type PostRn DocName (Located Name) Source #
type PostRn DocName (Located Name) = Located DocName

Instances

type DocInstance name = (InstHead name, Maybe (MDoc name), Located name) 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 kind parameters, a list of type parameters and an instance type

Documentation comments

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

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 mod, Eq id) => Eq (DocH mod id)
Methods (==) :: DocH mod id -> DocH mod id -> Bool # (/=) :: DocH mod id -> DocH mod id -> Bool #
(Show mod, Show id) => 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 Source #

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 Source #

Constructors

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

Instances

Functor Documentation Source #
Methods fmap :: (a -> b) -> Documentation a -> Documentation b # (<$) :: a -> Documentation b -> Documentation a #

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

type AliasMap = Map Module ModuleName Source #

type WarningMap = Map Name (Doc Name) Source #

type DocMap a = Map Name (MDoc a) Source #

data HaddockModInfo name Source #

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 Source #

Interface files

data InterfaceFile Source #

Constructors

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

Instances

Binary InterfaceFile Source #
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) Source #

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 Source #

freshNameCache :: NameCacheAccessor IO Source #

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

Flags and options

data Flag Source #

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 Source #
Methods (==) :: Flag -> Flag -> Bool # (/=) :: Flag -> Flag -> Bool #
Show Flag Source #
Methods showsPrec :: Int -> Flag -> ShowS # show :: Flag -> String # showList :: [Flag] -> ShowS #

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.

Instances

Eq DocOption Source #
Methods (==) :: DocOption -> DocOption -> Bool # (/=) :: DocOption -> DocOption -> Bool #
Show DocOption Source #
Methods showsPrec :: Int -> DocOption -> ShowS # show :: DocOption -> String # showList :: [DocOption] -> ShowS #

Error handling

data HaddockException Source #

Haddock's own exception type.

Constructors

HaddockException String

Instances

Show HaddockException Source #
Methods showsPrec :: Int -> HaddockException -> ShowS # show :: HaddockException -> String # showList :: [HaddockException] -> ShowS #
Exception HaddockException Source #
Methods toException :: HaddockException -> SomeException # fromException :: SomeException -> Maybe HaddockException # displayException :: HaddockException -> String #

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 (String, String) Source #

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