Modulehaddock-api-2.34.0Haskell2010

Documentation.Haddock

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

Contents

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

Synopsis

data Interface
data InstalledInterface
value toInstalledIface
value createInterfaces
value processModules
data ExportItem
type DocForDecl
type FnArgsDoc
type LinkEnv
data DocName
type DocInstance
data InstHead
type Doc
type MDoc
data DocH
data Example
data Hyperlink
type DocMarkup
data DocMarkupH
data Documentation
type ArgMap
type WarningMap
type DocMap
data HaddockModInfo
value markup
data InterfaceFile
value readInterfaceFile
value freshNameCache
data Flag
data DocOption
data HaddockException
value haddock
value haddockWithGhc
value getGhcDirs
value withGhc

Packagehaddock-api-2.34.0
Exports35
LanguageHaskell2010
LicenceBSD-2-Clause
SourceHaddock.hs

Interface

datadata 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
- ifaceMod :: !Module
  The module behind this interface.
- ifaceIsSig :: !Bool
  Is this a signature?
- 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).
- ifaceDocMap :: !DocMap Name
  Documentation of declarations originating from the module (including subordinates).
- ifaceArgMap :: !ArgMap Name
- ifaceDefMeths :: ![(OccName, Name)]
  The names of all the default methods for classes defined in this module
- ifaceFixMap :: !Map Name Fixity
- ifaceExportItems :: [ExportItem GhcRn]
- ifaceRnExportItems :: [ExportItem DocNameI]
- 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.
  Names from modules that are entirely re-exported don't count as visible.
- ifaceInstances :: [ClsInst]
  Instances exported by the module.
- ifaceOrphanDeps :: [Module]
  The list of modules to check for orphan instances if this module is imported.
- ifaceOrphanInstances :: [DocInstance GhcRn]
  Orphan instances
- ifaceRnOrphanInstances :: [DocInstance DocNameI]
- 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.
- ifaceHieFile :: !FilePath
  Tokenized source code of module (available if Haddock is invoked with source generation flag).
- ifaceDynFlags :: !DynFlags

datadata InstalledInterface

Source#

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

Constructors

InstalledInterface
- instMod :: Module
  The module represented by this interface.
- instIsSig :: Bool
  Is this a signature?
- instInfo :: HaddockModInfo Name
  Textual information about the module.
- instDocMap :: DocMap Name
  Documentation of declarations originating from the module (including subordinates).
- instArgMap :: ArgMap Name
- instDefMeths :: [(OccName, Name)]
  The names of all the default methods for classes defined in this module
- 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).
- instFixMap :: Map Name Fixity
- instWarningMap :: WarningMap
- instInstanceLocMap :: Map Name RealSrcSpan

Instances1Binary

Binary InstalledInterfaceDefined in haddock-api-2.34.0 · Haddock.InterfaceFile · orphan

valuetoInstalledIface :: Interface -> InstalledInterface

Source#

Convert an Interface to an InstalledInterface

valuecreateInterfaces

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

Source#

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.

valueprocessModules

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

Source#

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

datadata ExportItem name

Constructors

ExportDecl (XExportDecl name)
An exported declaration.
ExportNoDecl
An exported entity for which we have no documentation (perhaps because it resides in another package).
- expItemName :: !IdP name
- expItemSubs :: [IdP name]
  Subordinate names.
ExportGroup
A section heading.
- expItemSectionLevel :: !Int
  Section level (1, 2, 3, ...).
- expItemSectionId :: !String
  Section id (for hyperlinks).
- expItemSectionText :: !Doc (IdP name)
  Section heading text.
ExportDoc !(MDoc (IdP name))
Some documentation.
ExportModule !Module
A cross-reference to another module.

typetype DocForDecl name = (Documentation name, FnArgsDoc name)

typetype 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

typetype LinkEnv = Map Name Module

Source#

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

datadata 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.

Instances9Eq, Data, NamedThing, Outputable, Binary, OutputableBndr, …

Eq DocNameDefined in haddock-api-2.34.0 · Haddock.Types
Data DocNameDefined in haddock-api-2.34.0 · Haddock.Types
NamedThing DocNameDefined in haddock-api-2.34.0 · Haddock.Types
Outputable DocNameDefined in haddock-api-2.34.0 · Haddock.Types
Useful for debugging
Binary DocNameDefined in haddock-api-2.34.0 · Haddock.InterfaceFile · orphan
OutputableBndr DocNameDefined in haddock-api-2.34.0 · Haddock.Types
HasOccName DocNameDefined in haddock-api-2.34.0 · Haddock.Types
SetName DocNameDefined in haddock-api-2.34.0 · Haddock.Types
type Anno DocName = SrcSpanAnnNDefined in haddock-api-2.34.0 · Haddock.Types

Instances

typetype 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.

datadata 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

typetype Doc id = DocH (Wrap (ModuleName, OccName)) (Wrap id)

typetype MDoc id = MetaDoc (Wrap (ModuleName, OccName)) (Wrap id)

datadata DocH mod id

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

Instances10Bifoldable, Bifunctor, Bitraversable, Functor, Foldable, Traversable, …

Bifoldable DocHDefined in haddock-library-1.11.0 · Documentation.Haddock.Types
Bifunctor DocHDefined in haddock-library-1.11.0 · Documentation.Haddock.Types
Bitraversable DocHDefined in haddock-library-1.11.0 · Documentation.Haddock.Types
Functor (DocH mod)Defined in haddock-library-1.11.0 · Documentation.Haddock.Types
Foldable (DocH mod)Defined in haddock-library-1.11.0 · Documentation.Haddock.Types
Traversable (DocH mod)Defined in haddock-library-1.11.0 · Documentation.Haddock.Types
(Eq id, Eq mod) => Eq (DocH mod id)Defined in haddock-library-1.11.0 · Documentation.Haddock.Types
(Show id, Show mod) => Show (DocH mod id)Defined in haddock-library-1.11.0 · Documentation.Haddock.Types
(NFData a, NFData mod) => NFData (DocH mod a)Defined in haddock-api-2.34.0 · Haddock.Types · orphan
(Binary mod, Binary id) => Binary (DocH mod id)Defined in haddock-api-2.34.0 · Haddock.InterfaceFile · orphan

datadata Example

Constructors

Example
- exampleExpression :: String
- exampleResult :: [String]

Instances4Eq, Show, NFData, Binary

Eq ExampleDefined in haddock-library-1.11.0 · Documentation.Haddock.Types
Show ExampleDefined in haddock-library-1.11.0 · Documentation.Haddock.Types
NFData ExampleDefined in haddock-api-2.34.0 · Haddock.Types · orphan
Binary ExampleDefined in haddock-api-2.34.0 · Haddock.InterfaceFile · orphan

datadata Hyperlink id

Constructors

Hyperlink
- hyperlinkUrl :: String
- hyperlinkLabel :: Maybe id

Instances7Functor, Foldable, Traversable, Eq, Show, NFData, …

Functor HyperlinkDefined in haddock-library-1.11.0 · Documentation.Haddock.Types
Foldable HyperlinkDefined in haddock-library-1.11.0 · Documentation.Haddock.Types
Traversable HyperlinkDefined in haddock-library-1.11.0 · Documentation.Haddock.Types
Eq id => Eq (Hyperlink id)Defined in haddock-library-1.11.0 · Documentation.Haddock.Types
Show id => Show (Hyperlink id)Defined in haddock-library-1.11.0 · Documentation.Haddock.Types
NFData id => NFData (Hyperlink id)Defined in haddock-api-2.34.0 · Haddock.Types · orphan
Binary a => Binary (Hyperlink a)Defined in haddock-api-2.34.0 · Haddock.InterfaceFile · orphan

typetype DocMarkup id a = DocMarkupH (Wrap (ModuleName, OccName)) id a

datadata 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.

Constructors

Markup
- markupEmpty :: a
- markupString :: String -> a
- markupParagraph :: a -> a
- markupAppend :: a -> a -> a
- markupIdentifier :: id -> a
- markupIdentifierUnchecked :: mod -> a
- markupModule :: ModLink a -> a
- markupWarning :: a -> a
- markupEmphasis :: a -> a
- markupBold :: a -> a
- markupMonospaced :: a -> a
- markupUnorderedList :: [a] -> a
- markupOrderedList :: [(Int, a)] -> a
- markupDefList :: [(a, a)] -> a
- markupCodeBlock :: a -> a
- markupHyperlink :: Hyperlink a -> a
- markupAName :: String -> a
- markupPic :: Picture -> a
- markupMathInline :: String -> a
- markupMathDisplay :: String -> a
- markupProperty :: String -> a
- markupExample :: [Example] -> a
- markupHeader :: Header a -> a
- markupTable :: Table a -> a

datadata Documentation name

Constructors

Documentation
- documentationDoc :: Maybe (MDoc name)
- documentationWarning :: Maybe (Doc name)

Instances2Functor, NFData

Functor DocumentationDefined in haddock-api-2.34.0 · Haddock.Types
NFData name => NFData (Documentation name)Defined in haddock-api-2.34.0 · Haddock.Types

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

typetype WarningMap = Map Name (Doc Name)

typetype DocMap a = Map Name (MDoc a)

datadata HaddockModInfo name

Constructors

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 :: [Extension]

Instances2NFData, Binary

NFData name => NFData (HaddockModInfo name)Defined in haddock-api-2.34.0 · Haddock.Types
Binary name => Binary (HaddockModInfo name)Defined in haddock-api-2.34.0 · Haddock.InterfaceFile · orphan

valuemarkup :: DocMarkupH mod id a -> DocH mod id -> a

Interface files

datadata InterfaceFile

Constructors

InterfaceFile
- ifLinkEnv :: LinkEnv
- ifPackageInfo :: PackageInfo
  Package meta data. Currently it only consist of a package name, which is not read from the interface file, but inferred from its name.
  issue #
- ifInstalledIfaces :: [InstalledInterface]

Instances1Binary

Binary InterfaceFileDefined in haddock-api-2.34.0 · Haddock.InterfaceFile

valuereadInterfaceFile

:: NameCache
-> FilePath
-> Bool
Disable version check. Can cause runtime crash.
-> IO (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.

valuefreshNameCache :: IO NameCache

Flags and options

datadata Flag

Constructors

Flag_BuiltInThemes
Flag_CSS String
Flag_ReadInterface String
Flag_DumpInterface String
Flag_ShowInterface 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_BaseURL String
Flag_WikiModuleURL String
Flag_WikiEntityURL String
Flag_LaTeX
Flag_LaTeXStyle String
Flag_QuickJumpIndex
Flag_HyperlinkedSource
Flag_SourceCss String
Flag_Mathjax String
Flag_Help
Flag_Verbosity String
Flag_Version
Flag_CompatibleInterfaceVersions
Flag_InterfaceVersion
Flag_BypassInterfaceVersonCheck
Flag_UseContents String
Flag_GenContents
Flag_UseIndex String
Flag_GenIndex
Flag_IgnoreAllExports
Flag_HideModule String
Flag_ShowModule String
Flag_ShowAllModules
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
Flag_Reexport String
Flag_SinceQualification String
Flag_IgnoreLinkSymbol String
Flag_ParCount (Maybe Int)
Flag_TraceArgs
Flag_OneShot String
Flag_NoCompilation

Instances2Eq, Show

Eq FlagDefined in haddock-api-2.34.0 · Haddock.Options
Show FlagDefined in haddock-api-2.34.0 · Haddock.Options

datadata 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)
OptRedactTypeSyns
Hide the RHS of type synonyms in this module that use unexported types.

Instances3Eq, Show, Binary

Eq DocOptionDefined in haddock-api-2.34.0 · Haddock.Types
Show DocOptionDefined in haddock-api-2.34.0 · Haddock.Types
Binary DocOptionDefined in haddock-api-2.34.0 · Haddock.InterfaceFile · orphan