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


-- | The Haddock API: A rudimentary, 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 -> !Bool -> !HaddockModInfo Name -> !Documentation Name -> !Documentation DocName -> [DocOption] -> !DocMap Name -> !ArgMap Name -> ![(OccName, Name)] -> !Map Name Fixity -> [ExportItem GhcRn] -> [ExportItem DocNameI] -> [Name] -> [Name] -> [ClsInst] -> [DocInstance GhcRn] -> [DocInstance DocNameI] -> (Int, Int) -> WarningMap -> !FilePath -> !DynFlags -> Interface

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

-- | Is this a signature?
[ifaceIsSig] :: Interface -> !Bool

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

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

-- | The names of all the default methods for classes defined in this
--   module
[ifaceDefMeths] :: Interface -> ![(OccName, Name)]
[ifaceFixMap] :: Interface -> !Map Name Fixity
[ifaceExportItems] :: Interface -> [ExportItem GhcRn]
[ifaceRnExportItems] :: Interface -> [ExportItem DocNameI]

-- | 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.
--   
--   Names from modules that are entirely re-exported don't count as
--   visible.
[ifaceVisibleExports] :: Interface -> [Name]

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

-- | Orphan instances
[ifaceOrphanInstances] :: Interface -> [DocInstance GhcRn]
[ifaceRnOrphanInstances] :: Interface -> [DocInstance DocNameI]

-- | 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 (available if Haddock is invoked with
--   source generation flag).
[ifaceHieFile] :: Interface -> !FilePath
[ifaceDynFlags] :: Interface -> !DynFlags

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

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

-- | Is this a signature?
[instIsSig] :: InstalledInterface -> Bool

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

-- | The names of all the default methods for classes defined in this
--   module
[instDefMeths] :: InstalledInterface -> [(OccName, 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]
[instFixMap] :: InstalledInterface -> Map Name Fixity
[instWarningMap] :: InstalledInterface -> WarningMap
[instInstanceLocMap] :: InstalledInterface -> Map Name RealSrcSpan

-- | Convert an <a>Interface</a> to an <a>InstalledInterface</a>
toInstalledIface :: Interface -> InstalledInterface

-- | 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 :: XExportDecl name -> ExportItem name

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

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

-- | A section heading.
ExportGroup :: !Int -> !String -> !Doc (IdP 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 (IdP name)

-- | Some documentation.
ExportDoc :: !MDoc (IdP 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 IdP name, Located IdP name, Maybe Module)

-- | 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
data InstHead name
type Doc id = DocH Wrap (ModuleName, OccName) Wrap id
type MDoc id = MetaDoc Wrap (ModuleName, OccName) Wrap 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

-- | A qualified identifier that couldn't be resolved.
DocIdentifierUnchecked :: mod -> DocH mod id

-- | A link to a module, with an optional label.
DocModule :: ModLink (DocH mod id) -> DocH mod id

-- | This constructor has no counterpart in Haddock markup.
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 :: [(Int, 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) -> DocH mod id
DocPic :: Picture -> DocH mod id
DocMathInline :: String -> DocH mod id
DocMathDisplay :: String -> DocH mod id

-- | A (HTML) anchor. It must not contain any spaces.
DocAName :: String -> DocH mod id
DocProperty :: String -> DocH mod id
DocExamples :: [Example] -> DocH mod id
DocHeader :: Header (DocH mod id) -> DocH mod id
DocTable :: Table (DocH mod id) -> DocH mod id
data Example
Example :: String -> [String] -> Example
[exampleExpression] :: Example -> String
[exampleResult] :: Example -> [String]
data Hyperlink id
Hyperlink :: String -> Maybe id -> Hyperlink id
[hyperlinkUrl] :: Hyperlink id -> String
[hyperlinkLabel] :: Hyperlink id -> Maybe id
type DocMarkup id a = DocMarkupH Wrap (ModuleName, OccName) id a

-- | <a>DocMarkupH</a> is a set of instructions for marking up
--   documentation. In fact, it's really just a mapping from <tt>Doc</tt>
--   to some other type [a], where [a] is usually the type of the output
--   (HTML, say). Use <a>markup</a> to apply a <a>DocMarkupH</a> to a
--   <a>DocH</a>.
data DocMarkupH mod id a
Markup :: a -> (String -> a) -> (a -> a) -> (a -> a -> a) -> (id -> a) -> (mod -> a) -> (ModLink a -> a) -> (a -> a) -> (a -> a) -> (a -> a) -> (a -> a) -> ([a] -> a) -> ([(Int, a)] -> a) -> ([(a, a)] -> a) -> (a -> a) -> (Hyperlink a -> a) -> (String -> a) -> (Picture -> a) -> (String -> a) -> (String -> a) -> (String -> a) -> ([Example] -> a) -> (Header a -> a) -> (Table a -> a) -> DocMarkupH mod id a
[markupEmpty] :: DocMarkupH mod id a -> a
[markupString] :: DocMarkupH mod id a -> String -> a
[markupParagraph] :: DocMarkupH mod id a -> a -> a
[markupAppend] :: DocMarkupH mod id a -> a -> a -> a
[markupIdentifier] :: DocMarkupH mod id a -> id -> a
[markupIdentifierUnchecked] :: DocMarkupH mod id a -> mod -> a
[markupModule] :: DocMarkupH mod id a -> ModLink a -> a
[markupWarning] :: DocMarkupH mod id a -> a -> a
[markupEmphasis] :: DocMarkupH mod id a -> a -> a
[markupBold] :: DocMarkupH mod id a -> a -> a
[markupMonospaced] :: DocMarkupH mod id a -> a -> a
[markupUnorderedList] :: DocMarkupH mod id a -> [a] -> a
[markupOrderedList] :: DocMarkupH mod id a -> [(Int, a)] -> a
[markupDefList] :: DocMarkupH mod id a -> [(a, a)] -> a
[markupCodeBlock] :: DocMarkupH mod id a -> a -> a
[markupHyperlink] :: DocMarkupH mod id a -> Hyperlink a -> a
[markupAName] :: DocMarkupH mod id a -> String -> a
[markupPic] :: DocMarkupH mod id a -> Picture -> a
[markupMathInline] :: DocMarkupH mod id a -> String -> a
[markupMathDisplay] :: DocMarkupH mod id a -> String -> a
[markupProperty] :: DocMarkupH mod id a -> String -> a
[markupExample] :: DocMarkupH mod id a -> [Example] -> a
[markupHeader] :: DocMarkupH mod id a -> Header a -> a
[markupTable] :: DocMarkupH mod id a -> Table 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 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 :: DocMarkupH mod id a -> DocH mod id -> a
data InterfaceFile
InterfaceFile :: LinkEnv -> PackageInfo -> [InstalledInterface] -> InterfaceFile
[ifLinkEnv] :: InterfaceFile -> LinkEnv

-- | 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 #
[ifPackageInfo] :: InterfaceFile -> PackageInfo
[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.
readInterfaceFile :: NameCache -> FilePath -> Bool -> IO (Either String InterfaceFile)
freshNameCache :: IO NameCache
data Flag
Flag_BuiltInThemes :: Flag
Flag_CSS :: String -> Flag
Flag_ReadInterface :: String -> Flag
Flag_DumpInterface :: String -> Flag
Flag_ShowInterface :: 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_BaseURL :: String -> Flag
Flag_WikiModuleURL :: String -> Flag
Flag_WikiEntityURL :: String -> Flag
Flag_LaTeX :: Flag
Flag_LaTeXStyle :: String -> Flag
Flag_QuickJumpIndex :: 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_BypassInterfaceVersonCheck :: Flag
Flag_UseContents :: String -> Flag
Flag_GenContents :: Flag
Flag_UseIndex :: String -> Flag
Flag_GenIndex :: Flag
Flag_IgnoreAllExports :: Flag
Flag_HideModule :: String -> Flag
Flag_ShowModule :: String -> Flag
Flag_ShowAllModules :: 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
Flag_Reexport :: String -> Flag
Flag_SinceQualification :: String -> Flag
Flag_IgnoreLinkSymbol :: String -> Flag
Flag_ParCount :: Maybe Int -> Flag
Flag_TraceArgs :: Flag
Flag_OneShot :: String -> Flag
Flag_NoCompilation :: 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

-- | Render runtime reps for this module (see the GHC
--   <tt>-fprint-explicit-runtime-reps</tt> flag)
OptPrintRuntimeRep :: DocOption

-- | Haddock's own exception type.
data HaddockException
HaddockException :: String -> HaddockException
WithContext :: [String] -> SomeException -> 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 ()

-- | Find the <tt>lib</tt> directory for GHC and the path to <tt>ghc</tt>
getGhcDirs :: [Flag] -> IO (Maybe FilePath, Maybe FilePath)
withGhc :: [Flag] -> Ghc a -> IO a
