-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A documentation-generation tool for Haskell libraries
--   
--   Haddock is a documentation-generation tool for Haskell libraries
@package haddock-api
@version 2.17.3


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

-- | <a>Interface</a> holds all information used to render a single Haddock
--   page. It represents the <i>interface</i> 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.
data Interface
Interface :: !Module -> !FilePath -> !(HaddockModInfo Name) -> !(Documentation Name) -> !(Documentation DocName) -> ![DocOption] -> !(Map Name [LHsDecl Name]) -> !(DocMap Name) -> !(ArgMap Name) -> !(DocMap DocName) -> !(ArgMap DocName) -> !(Map Name [Name]) -> !(Map Name Fixity) -> ![ExportItem Name] -> ![ExportItem DocName] -> ![Name] -> ![Name] -> !AliasMap -> ![ClsInst] -> ![FamInst] -> ![DocInstance Name] -> ![DocInstance DocName] -> !(Int, Int) -> !WarningMap -> !(Maybe [RichToken]) -> Interface

-- | The module behind this interface.
[ifaceMod] :: Interface -> !Module

-- | Original file name of the module.
[ifaceOrigFilename] :: Interface -> !FilePath

-- | Textual information about the module.
[ifaceInfo] :: Interface -> !(HaddockModInfo Name)

-- | Documentation header.
[ifaceDoc] :: Interface -> !(Documentation Name)

-- | Documentation header with cross-reference information.
[ifaceRnDoc] :: Interface -> !(Documentation DocName)

-- | Haddock options for this module (prune, ignore-exports, etc).
[ifaceOptions] :: Interface -> ![DocOption]

-- | 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.
[ifaceDeclMap] :: Interface -> !(Map Name [LHsDecl Name])

-- | Documentation of declarations originating from the module (including
--   subordinates).
[ifaceDocMap] :: Interface -> !(DocMap Name)
[ifaceArgMap] :: Interface -> !(ArgMap Name)

-- | Documentation of declarations originating from the module (including
--   subordinates).
[ifaceRnDocMap] :: Interface -> !(DocMap DocName)
[ifaceRnArgMap] :: Interface -> !(ArgMap DocName)
[ifaceSubMap] :: Interface -> !(Map Name [Name])
[ifaceFixMap] :: Interface -> !(Map Name Fixity)
[ifaceExportItems] :: Interface -> ![ExportItem Name]
[ifaceRnExportItems] :: Interface -> ![ExportItem DocName]

-- | All names exported by the module.
[ifaceExports] :: Interface -> ![Name]

-- | All "visible" names exported by the module. A visible name is a name
--   that will show up in the documentation of the module.
[ifaceVisibleExports] :: Interface -> ![Name]

-- | Aliases of module imports as in <tt>import A.B.C as C</tt>.
[ifaceModuleAliases] :: Interface -> !AliasMap

-- | Instances exported by the module.
[ifaceInstances] :: Interface -> ![ClsInst]
[ifaceFamInstances] :: Interface -> ![FamInst]

-- | Orphan instances
[ifaceOrphanInstances] :: Interface -> ![DocInstance Name]
[ifaceRnOrphanInstances] :: Interface -> ![DocInstance DocName]

-- | The number of haddockable and haddocked items in the module, as a
--   tuple. Haddockable items are the exports and the module itself.
[ifaceHaddockCoverage] :: Interface -> !(Int, Int)

-- | Warnings for things defined in this module.
[ifaceWarningMap] :: Interface -> !WarningMap

-- | Tokenized source code of module (avaliable if Haddock is invoked with
--   source generation flag).
[ifaceTokenizedSrc] :: Interface -> !(Maybe [RichToken])

-- | A subset of the fields of <a>Interface</a> that we store in the
--   interface files.
data InstalledInterface
InstalledInterface :: Module -> HaddockModInfo Name -> DocMap Name -> ArgMap Name -> [Name] -> [Name] -> [DocOption] -> Map Name [Name] -> Map Name Fixity -> InstalledInterface

-- | The module represented by this interface.
[instMod] :: InstalledInterface -> Module

-- | Textual information about the module.
[instInfo] :: InstalledInterface -> HaddockModInfo Name

-- | Documentation of declarations originating from the module (including
--   subordinates).
[instDocMap] :: InstalledInterface -> DocMap Name
[instArgMap] :: InstalledInterface -> ArgMap Name

-- | All names exported by this module.
[instExports] :: InstalledInterface -> [Name]

-- | All "visible" names exported by the module. A visible name is a name
--   that will show up in the documentation of the module.
[instVisibleExports] :: InstalledInterface -> [Name]

-- | Haddock options for this module (prune, ignore-exports, etc).
[instOptions] :: InstalledInterface -> [DocOption]
[instSubMap] :: InstalledInterface -> Map Name [Name]
[instFixMap] :: InstalledInterface -> Map Name Fixity

-- | Create <a>Interface</a> structures from a given list of Haddock
--   command-line flags and file or module names (as accepted by
--   <a>haddock</a> executable). Flags that control documentation
--   generation or show help or version information are ignored.
createInterfaces :: [Flag] -> [String] -> IO [Interface]

-- | Create <a>Interface</a>s and a link environment by typechecking the
--   list of modules using the GHC API and processing the resulting syntax
--   trees.
processModules :: Verbosity -> [String] -> [Flag] -> [InterfaceFile] -> Ghc ([Interface], LinkEnv)
data ExportItem name

-- | An exported declaration.
ExportDecl :: !(LHsDecl name) -> !(DocForDecl name) -> ![(name, DocForDecl name)] -> ![DocInstance name] -> ![(name, Fixity)] -> !Bool -> ExportItem name

-- | A declaration.
[expItemDecl] :: ExportItem name -> !(LHsDecl name)

-- | Maybe a doc comment, and possibly docs for arguments (if this decl is
--   a function or type-synonym).
[expItemMbDoc] :: ExportItem name -> !(DocForDecl name)

-- | Subordinate names, possibly with documentation.
[expItemSubDocs] :: ExportItem name -> ![(name, DocForDecl name)]

-- | Instances relevant to this declaration, possibly with documentation.
[expItemInstances] :: ExportItem name -> ![DocInstance name]

-- | Fixity decls relevant to this declaration (including subordinates).
[expItemFixities] :: ExportItem name -> ![(name, Fixity)]

-- | Whether the ExportItem is from a TH splice or not, for generating the
--   appropriate type of Source link.
[expItemSpliced] :: ExportItem name -> !Bool

-- | An exported entity for which we have no documentation (perhaps because
--   it resides in another package).
ExportNoDecl :: !name -> ![name] -> ExportItem name
[expItemName] :: ExportItem name -> !name

-- | Subordinate names.
[expItemSubs] :: ExportItem name -> ![name]

-- | A section heading.
ExportGroup :: !Int -> !String -> !(Doc name) -> ExportItem name

-- | Section level (1, 2, 3, ...).
[expItemSectionLevel] :: ExportItem name -> !Int

-- | Section id (for hyperlinks).
[expItemSectionId] :: ExportItem name -> !String

-- | Section heading text.
[expItemSectionText] :: ExportItem name -> !(Doc name)

-- | Some documentation.
ExportDoc :: !(MDoc name) -> ExportItem name

-- | A cross-reference to another module.
ExportModule :: !Module -> ExportItem name
type DocForDecl name = (Documentation name, FnArgsDoc name)

-- | Arguments and result are indexed by Int, zero-based from the left,
--   because that's the easiest to use when recursing over types.
type FnArgsDoc name = Map Int (MDoc name)

-- | Type of environment used to cross-reference identifiers in the syntax.
type LinkEnv = Map Name Module

-- | Extends <a>Name</a> with cross-reference information.
data DocName

-- | This thing is part of the (existing or resulting) documentation. The
--   <a>Module</a> is the preferred place in the documentation to refer to.
Documented :: Name -> Module -> DocName

-- | This thing is not part of the (existing or resulting) documentation,
--   as far as Haddock knows.
Undocumented :: Name -> DocName

-- | An instance head that may have documentation and a source location.
type DocInstance name = (InstHead name, Maybe (MDoc name), Located 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
data InstHead name
type Doc id = DocH (ModuleName, OccName) id
data DocH mod id :: * -> * -> *
DocEmpty :: DocH mod id
DocAppend :: DocH mod id -> DocH mod id -> DocH mod id
DocString :: String -> DocH mod id
DocParagraph :: DocH mod id -> DocH mod id
DocIdentifier :: id -> DocH mod id
DocIdentifierUnchecked :: mod -> DocH mod id
DocModule :: String -> DocH mod id
DocWarning :: DocH mod id -> DocH mod id
DocEmphasis :: DocH mod id -> DocH mod id
DocMonospaced :: DocH mod id -> DocH mod id
DocBold :: DocH mod id -> DocH mod id
DocUnorderedList :: [DocH mod id] -> DocH mod id
DocOrderedList :: [DocH mod id] -> DocH mod id
DocDefList :: [(DocH mod id, DocH mod id)] -> DocH mod id
DocCodeBlock :: DocH mod id -> DocH mod id
DocHyperlink :: Hyperlink -> DocH mod id
DocPic :: Picture -> DocH mod id
DocMathInline :: String -> DocH mod id
DocMathDisplay :: String -> DocH mod id
DocAName :: String -> DocH mod id
DocProperty :: String -> DocH mod id
DocExamples :: [Example] -> DocH mod id
DocHeader :: Header (DocH mod id) -> DocH mod id
data Example :: *
Example :: String -> [String] -> Example
[exampleExpression] :: Example -> String
[exampleResult] :: Example -> [String]
data Hyperlink :: *
Hyperlink :: String -> Maybe String -> Hyperlink
[hyperlinkUrl] :: Hyperlink -> String
[hyperlinkLabel] :: Hyperlink -> Maybe String
data DocMarkup id a
Markup :: a -> (String -> a) -> (a -> a) -> (a -> a -> a) -> (id -> a) -> ((ModuleName, OccName) -> a) -> (String -> a) -> (a -> a) -> (a -> a) -> (a -> a) -> (a -> a) -> ([a] -> a) -> ([a] -> a) -> ([(a, a)] -> a) -> (a -> a) -> (Hyperlink -> a) -> (String -> a) -> (Picture -> a) -> (String -> a) -> (String -> a) -> (String -> a) -> ([Example] -> a) -> (Header a -> a) -> DocMarkup id a
[markupEmpty] :: DocMarkup id a -> a
[markupString] :: DocMarkup id a -> String -> a
[markupParagraph] :: DocMarkup id a -> a -> a
[markupAppend] :: DocMarkup id a -> a -> a -> a
[markupIdentifier] :: DocMarkup id a -> id -> a
[markupIdentifierUnchecked] :: DocMarkup id a -> (ModuleName, OccName) -> a
[markupModule] :: DocMarkup id a -> String -> a
[markupWarning] :: DocMarkup id a -> a -> a
[markupEmphasis] :: DocMarkup id a -> a -> a
[markupBold] :: DocMarkup id a -> a -> a
[markupMonospaced] :: DocMarkup id a -> a -> a
[markupUnorderedList] :: DocMarkup id a -> [a] -> a
[markupOrderedList] :: DocMarkup id a -> [a] -> a
[markupDefList] :: DocMarkup id a -> [(a, a)] -> a
[markupCodeBlock] :: DocMarkup id a -> a -> a
[markupHyperlink] :: DocMarkup id a -> Hyperlink -> a
[markupAName] :: DocMarkup id a -> String -> a
[markupPic] :: DocMarkup id a -> Picture -> a
[markupMathInline] :: DocMarkup id a -> String -> a
[markupMathDisplay] :: DocMarkup id a -> String -> a
[markupProperty] :: DocMarkup id a -> String -> a
[markupExample] :: DocMarkup id a -> [Example] -> a
[markupHeader] :: DocMarkup id a -> Header a -> a
data Documentation name
Documentation :: Maybe (MDoc name) -> !(Maybe (Doc name)) -> Documentation name
[documentationDoc] :: Documentation name -> Maybe (MDoc name)
[documentationWarning] :: Documentation name -> !(Maybe (Doc name))
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
HaddockModInfo :: Maybe (Doc name) -> Maybe String -> Maybe String -> Maybe String -> Maybe String -> Maybe String -> Maybe String -> Maybe Language -> [Extension] -> HaddockModInfo name
[hmi_description] :: HaddockModInfo name -> Maybe (Doc name)
[hmi_copyright] :: HaddockModInfo name -> Maybe String
[hmi_license] :: HaddockModInfo name -> Maybe String
[hmi_maintainer] :: HaddockModInfo name -> Maybe String
[hmi_stability] :: HaddockModInfo name -> Maybe String
[hmi_portability] :: HaddockModInfo name -> Maybe String
[hmi_safety] :: HaddockModInfo name -> Maybe String
[hmi_language] :: HaddockModInfo name -> Maybe Language
[hmi_extensions] :: HaddockModInfo name -> [Extension]
markup :: DocMarkup id a -> Doc id -> a
data InterfaceFile
InterfaceFile :: LinkEnv -> [InstalledInterface] -> InterfaceFile
[ifLinkEnv] :: InterfaceFile -> LinkEnv
[ifInstalledIfaces] :: InterfaceFile -> [InstalledInterface]

-- | Read a Haddock (<tt>.haddock</tt>) interface file. Return either an
--   <a>InterfaceFile</a> 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.
readInterfaceFile :: forall m. 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
Flag_CSS :: String -> Flag
Flag_ReadInterface :: String -> Flag
Flag_DumpInterface :: String -> Flag
Flag_Heading :: String -> Flag
Flag_Html :: Flag
Flag_Hoogle :: Flag
Flag_Lib :: String -> Flag
Flag_OutputDir :: FilePath -> Flag
Flag_Prologue :: FilePath -> Flag
Flag_SourceBaseURL :: String -> Flag
Flag_SourceModuleURL :: String -> Flag
Flag_SourceEntityURL :: String -> Flag
Flag_SourceLEntityURL :: String -> Flag
Flag_WikiBaseURL :: String -> Flag
Flag_WikiModuleURL :: String -> Flag
Flag_WikiEntityURL :: String -> Flag
Flag_LaTeX :: Flag
Flag_LaTeXStyle :: String -> Flag
Flag_HyperlinkedSource :: Flag
Flag_SourceCss :: String -> Flag
Flag_Mathjax :: String -> Flag
Flag_Help :: Flag
Flag_Verbosity :: String -> Flag
Flag_Version :: Flag
Flag_CompatibleInterfaceVersions :: Flag
Flag_InterfaceVersion :: Flag
Flag_UseContents :: String -> Flag
Flag_GenContents :: Flag
Flag_UseIndex :: String -> Flag
Flag_GenIndex :: Flag
Flag_IgnoreAllExports :: Flag
Flag_HideModule :: String -> Flag
Flag_ShowExtensions :: String -> Flag
Flag_OptGhc :: String -> Flag
Flag_GhcLibDir :: String -> Flag
Flag_GhcVersion :: Flag
Flag_PrintGhcPath :: Flag
Flag_PrintGhcLibDir :: Flag
Flag_NoWarnings :: Flag
Flag_UseUnicode :: Flag
Flag_NoTmpCompDir :: Flag
Flag_Qualification :: String -> Flag
Flag_PrettyHtml :: Flag
Flag_NoPrintMissingDocs :: Flag
Flag_PackageName :: String -> Flag
Flag_PackageVersion :: String -> Flag

-- | Source-level options for controlling the documentation.
data DocOption

-- | This module should not appear in the docs.
OptHide :: DocOption
OptPrune :: DocOption

-- | Pretend everything is exported.
OptIgnoreExports :: DocOption

-- | Not the best place to get docs for things exported by this module.
OptNotHome :: DocOption

-- | Render enabled extensions for this module.
OptShowExtensions :: DocOption

-- | Haddock's own exception type.
data HaddockException
HaddockException :: String -> HaddockException

-- | Run Haddock with given list of arguments.
--   
--   Haddock's own main function is defined in terms of this:
--   
--   <pre>
--   main = getArgs &gt;&gt;= haddock
--   </pre>
haddock :: [String] -> IO ()
haddockWithGhc :: (forall a. [Flag] -> Ghc a -> IO a) -> [String] -> IO ()
getGhcDirs :: [Flag] -> IO (String, String)
withGhc :: [Flag] -> Ghc a -> IO a
