Portability | portable |
---|---|
Stability | experimental |
Maintainer | haddock@projects.haskellorg |
The Haddock API: A rudimentory, highly experimental API exposing some of the internals of Haddock. Don't expect it to be stable.
- data Interface = Interface {
- ifaceMod :: Module
- ifaceOrigFilename :: FilePath
- ifaceInfo :: !(HaddockModInfo Name)
- ifaceDoc :: !(Maybe (Doc Name))
- ifaceRnDoc :: Maybe (Doc DocName)
- ifaceOptions :: ![DocOption]
- ifaceDeclMap :: Map Name DeclInfo
- ifaceRnDocMap :: Map Name (DocForDecl DocName)
- ifaceSubMap :: Map Name [Name]
- ifaceExportItems :: ![ExportItem Name]
- ifaceRnExportItems :: [ExportItem DocName]
- ifaceExports :: ![Name]
- ifaceVisibleExports :: ![Name]
- ifaceInstances :: ![Instance]
- ifaceInstanceDocMap :: Map Name (Doc Name)
- data InstalledInterface = InstalledInterface {
- instMod :: Module
- instInfo :: HaddockModInfo Name
- instDocMap :: Map Name (DocForDecl Name)
- instExports :: [Name]
- instVisibleExports :: [Name]
- instOptions :: [DocOption]
- instSubMap :: Map Name [Name]
- createInterfaces :: Verbosity -> [String] -> [Flag] -> [InterfaceFile] -> Ghc ([Interface], LinkEnv)
- data ExportItem name
- = ExportDecl {
- expItemDecl :: LHsDecl name
- expItemMbDoc :: DocForDecl name
- expItemSubDocs :: [(name, DocForDecl name)]
- expItemInstances :: [DocInstance name]
- | ExportNoDecl {
- expItemName :: name
- expItemSubs :: [name]
- | ExportGroup {
- expItemSectionLevel :: Int
- expItemSectionId :: String
- expItemSectionText :: Doc name
- | ExportDoc (Doc name)
- | ExportModule Module
- = ExportDecl {
- type DeclInfo = (Decl, DocForDecl Name, [(Name, DocForDecl Name)])
- type DocForDecl name = (Maybe (Doc name), FnArgsDoc name)
- type FnArgsDoc name = Map Int (Doc name)
- type LinkEnv = Map Name Module
- data DocName
- docNameOcc :: DocName -> OccName
- type DocInstance name = (InstHead name, Maybe (Doc name))
- type InstHead name = ([HsPred name], name, [HsType name])
- data Doc id
- = DocEmpty
- | DocAppend (Doc id) (Doc id)
- | DocString String
- | DocParagraph (Doc id)
- | DocIdentifier [id]
- | DocModule String
- | DocEmphasis (Doc id)
- | DocMonospaced (Doc id)
- | DocUnorderedList [Doc id]
- | DocOrderedList [Doc id]
- | DocDefList [(Doc id, Doc id)]
- | DocCodeBlock (Doc id)
- | DocURL String
- | DocPic String
- | DocAName String
- data DocMarkup id a = Markup {
- markupEmpty :: a
- markupString :: String -> a
- markupParagraph :: a -> a
- markupAppend :: a -> a -> a
- markupIdentifier :: [id] -> a
- markupModule :: String -> a
- markupEmphasis :: a -> a
- markupMonospaced :: a -> a
- markupUnorderedList :: [a] -> a
- markupOrderedList :: [a] -> a
- markupDefList :: [(a, a)] -> a
- markupCodeBlock :: a -> a
- markupURL :: String -> a
- markupAName :: String -> a
- markupPic :: String -> a
- data HaddockModInfo name = HaddockModInfo {
- hmi_description :: Maybe (Doc name)
- hmi_portability :: Maybe String
- hmi_stability :: Maybe String
- hmi_maintainer :: Maybe String
- data InterfaceFile = InterfaceFile {}
- readInterfaceFile :: 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_CSS String
- | Flag_Debug
- | Flag_ReadInterface String
- | Flag_DumpInterface String
- | Flag_Heading String
- | Flag_Html
- | Flag_Hoogle
- | Flag_HtmlHelp String
- | Flag_Lib String
- | Flag_OutputDir FilePath
- | Flag_Prologue FilePath
- | Flag_SourceBaseURL String
- | Flag_SourceModuleURL String
- | Flag_SourceEntityURL String
- | Flag_WikiBaseURL String
- | Flag_WikiModuleURL String
- | Flag_WikiEntityURL String
- | Flag_Help
- | Flag_Verbosity String
- | Flag_Version
- | Flag_UseContents String
- | Flag_GenContents
- | Flag_UseIndex String
- | Flag_GenIndex
- | Flag_IgnoreAllExports
- | Flag_HideModule String
- | Flag_OptGhc String
- | Flag_GhcLibDir String
- | Flag_GhcVersion
- | Flag_PrintGhcLibDir
- | Flag_NoWarnings
- | Flag_UseUnicode
- data DocOption
- = OptHide
- | OptPrune
- | OptIgnoreExports
- | OptNotHome
Interface
The data structure used to render a Haddock page for a module - it is the interface of the module. The core of Haddock lies in creating this structure (see Haddock.Interface). The structure also holds intermediate data needed during its creation.
Interface | |
|
data InstalledInterface Source
A smaller version of Interface
that can be created from Haddock's
interface files (InterfaceFile
).
InstalledInterface | |
|
:: Verbosity | Verbosity of logging to |
-> [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 Interface
structures by typechecking the list of modules
using the GHC API and processing the resulting syntax trees.
Export items & declarations
data ExportItem name Source
ExportDecl | An exported declaration |
| |
ExportNoDecl | An exported entity for which we have no documentation (perhaps because it resides in another package) |
| |
ExportGroup | A section heading |
| |
ExportDoc (Doc name) | Some documentation |
ExportModule Module | A cross-reference to another module |
type DeclInfo = (Decl, DocForDecl Name, [(Name, DocForDecl Name)])Source
A declaration that may have documentation, including its subordinates, which may also have documentation
type DocForDecl name = (Maybe (Doc name), FnArgsDoc name)Source
type FnArgsDoc name = Map Int (Doc 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.
Hyperlinking
An extension of Name
that may contain the preferred place to link to in
the documentation.
docNameOcc :: DocName -> OccNameSource
The OccName
of this name.
Instances
type DocInstance name = (InstHead name, Maybe (Doc name))Source
An instance head that may have documentation.
type InstHead name = ([HsPred name], name, [HsType name])Source
The head of an instance. Consists of a context, a class name and a list of instance types.
Documentation comments
DocEmpty | |
DocAppend (Doc id) (Doc id) | |
DocString String | |
DocParagraph (Doc id) | |
DocIdentifier [id] | |
DocModule String | |
DocEmphasis (Doc id) | |
DocMonospaced (Doc id) | |
DocUnorderedList [Doc id] | |
DocOrderedList [Doc id] | |
DocDefList [(Doc id, Doc id)] | |
DocCodeBlock (Doc id) | |
DocURL String | |
DocPic String | |
DocAName String |
Markup | |
|
data HaddockModInfo name Source
HaddockModInfo | |
|
Binary name => Binary (HaddockModInfo name) |
Interface files
(.haddock files)
data InterfaceFile Source
readInterfaceFile :: 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.
type NameCacheAccessor m = (m NameCache, NameCache -> m ())Source
Flags and options
Source-level options for controlling the documentation.
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. |