{-# OPTIONS_HADDOCK hide #-}{-# LANGUAGE DeriveDataTypeable #-}------------------------------------------------------------------------------- |-- Module : Haddock.Types-- Copyright : (c) Simon Marlow 2003-2006,-- David Waern 2006-2009-- License : BSD-like---- Maintainer : haddock@projects.haskellorg-- Stability : experimental-- Portability : portable---- Types that are commonly used through-out Haddock. Some of the most-- important types are defined here, like 'Interface' and 'DocName'.-----------------------------------------------------------------------------moduleHaddock.Types(moduleHaddock.Types-- avoid duplicate-export warnings, use the conditional to only-- mention things not defined in this module:#if __GLASGOW_HASKELL__ >= 611,HsDocString,LHsDocString#else,HsDoc(..),LHsDoc,HaddockModInfo(..),emptyHaddockModInfo#endif)whereimportControl.ExceptionimportData.TypeableimportData.Map(Map)importqualifiedData.MapasMapimportGHChiding(NoLink)importName-- convenient short-handstypeDecl=LHsDeclNametypeDoc=HsDocName#if __GLASGOW_HASKELL__ <= 610typeHsDocString=HsDocNametypeLHsDocString=LocatedHsDocString#endif-- | Arguments and result are indexed by Int, zero-based from the left,-- because that's the easiest to use when recursing over types.typeFnArgsDocname=MapInt(HsDocname)typeDocForDeclname=(Maybe(HsDocname),FnArgsDocname)noDocForDecl::DocForDeclnamenoDocForDecl=(Nothing,Map.empty)-- | A declaration that may have documentation, including its subordinates,-- which may also have documentationtypeDeclInfo=(Decl,DocForDeclName,[(Name,DocForDeclName)])-- | A 'DocName' is an identifier that may be documented. The 'Module'-- component specifies the place which we want to link to in the documentation.dataDocName=DocumentedNameModule|UndocumentedNamederivingEq-- | The 'OccName' belonging to this namedocNameOcc::DocName->OccNamedocNameOcc=nameOccName.getNameinstanceNamedThingDocNamewheregetName(Documentedname_)=namegetName(Undocumentedname)=name{-! for DocOption derive: Binary !-}dataDocOption=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.deriving(Eq,Show)dataExportItemname=ExportDecl{-- | A declarationexpItemDecl::LHsDeclname,-- | Maybe a doc comment, and possibly docs for arguments (if this-- decl is a function or type-synonym)expItemMbDoc::DocForDeclname,-- | Subordinate names, possibly with documentationexpItemSubDocs::[(name,DocForDeclname)],-- | Instances relevant to this declarationexpItemInstances::[InstHeadname]}-- ^ An exported declaration |ExportNoDecl{expItemName::name,-- | Subordinate namesexpItemSubs::[name]}-- ^ An exported entity for which we have no -- documentation (perhaps because it resides in-- another package)|ExportGroup{-- | Section level (1, 2, 3, ... )expItemSectionLevel::Int,-- | Section id (for hyperlinks)expItemSectionId::String,-- | Section heading textexpItemSectionText::HsDocname}-- ^ A section heading|ExportDoc(HsDocname)-- ^ Some documentation|ExportModuleModule-- ^ A cross-reference to another moduletypeInstHeadname=([HsPredname],name,[HsTypename])typeModuleMap=MapModuleInterfacetypeInstIfaceMap=MapModuleInstalledInterfacetypeDocMap=MapName(HsDocDocName)typeLinkEnv=MapNameModule#if __GLASGOW_HASKELL__ >= 611typeGhcDocHdr=MaybeLHsDocString#elsetypeGhcDocHdr=(HaddockModInfoName,Maybe(HsDocName))#endif-- | This structure holds the module information we get from GHC's -- type checking phasedataGhcModule=GhcModule{ghcModule::Module,ghcFilename::FilePath,ghcMbDocOpts::MaybeString,ghcMbDocHdr::GhcDocHdr,ghcGroup::HsGroupName,ghcMbExports::Maybe[LIEName],ghcExportedNames::[Name],ghcDefinedNames::[Name],ghcNamesInScope::[Name],ghcInstances::[Instance]}-- | This is 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.dataInterface=Interface{-- | The module represented by this interfaceifaceMod::Module,-- | The original filename for this moduleifaceOrigFilename::FilePath,-- | Textual information about the module ifaceInfo::!(HaddockModInfoName),-- | The documentation header for this moduleifaceDoc::!(Maybe(HsDocName)),-- | The renamed documentation header for this moduleifaceRnDoc::Maybe(HsDocDocName),-- | The Haddock options for this module (prune, ignore-exports, etc)ifaceOptions::![DocOption],-- | The declarations of the module. Excludes declarations that don't-- have names (instances and stand-alone documentation comments). Includes-- subordinate names, but they are mapped to their parent declarations.ifaceDeclMap::MapNameDeclInfo,-- | Everything declared in the module (including subordinates) that has docsifaceRnDocMap::MapName(DocForDeclDocName),ifaceSubMap::MapName[Name],ifaceExportItems::![ExportItemName],ifaceRnExportItems::[ExportItemDocName],-- | All names defined in this moduleifaceLocals::![Name],-- | All names exported by this moduleifaceExports::![Name],-- | All the visible names exported by this module-- For a name to be visible, it has to:---- * be exported normally, and not via a full module re-exportation.---- * have a declaration in this module or any of it's imports, with the-- exception that it can't be from another package.---- Basically, a visible name is a name that will show up in the documentation-- for this module.ifaceVisibleExports::![Name],-- | The instances exported by this moduleifaceInstances::![Instance]}-- | A smaller version of 'Interface' that we can get from the Haddock-- interface files.dataInstalledInterface=InstalledInterface{-- | The module represented by this interfaceinstMod::Module,-- | Textual information about the module instInfo::HaddockModInfoName,-- | Everything declared in the module (including subordinates) that has docsinstDocMap::MapName(DocForDeclName),-- | All names exported by this moduleinstExports::[Name],-- | All the visible names exported by this module-- For a name to be visible, it has to:---- * be exported normally, and not via a full module re-exportation.---- * have a declaration in this module or any of it's imports, with the-- exception that it can't be from another package.---- Basically, a visible name is a name that will show up in the documentation-- for this module.instVisibleExports::[Name],-- | The Haddock options for this module (prune, ignore-exports, etc)instOptions::[DocOption],instSubMap::MapName[Name]}-- | Convert an 'Interface' to an 'InstalledInterface'toInstalledIface::Interface->InstalledInterfacetoInstalledIfaceinterface=InstalledInterface{instMod=ifaceModinterface,instInfo=ifaceInfointerface,instDocMap=fmapunrenameDocForDecl$ifaceRnDocMapinterface,instExports=ifaceExportsinterface,instVisibleExports=ifaceVisibleExportsinterface,instOptions=ifaceOptionsinterface,instSubMap=ifaceSubMapinterface}unrenameHsDoc::HsDocDocName->HsDocNameunrenameHsDoc=fmapHsDocgetNameunrenameDocForDecl::DocForDeclDocName->DocForDeclNameunrenameDocForDecl(mbDoc,fnArgsDoc)=(fmapunrenameHsDocmbDoc,fmapunrenameHsDocfnArgsDoc)#if __GLASGOW_HASKELL__ >= 611dataHsDocid=DocEmpty|DocAppend(HsDocid)(HsDocid)|DocStringString|DocParagraph(HsDocid)|DocIdentifier[id]|DocModuleString|DocEmphasis(HsDocid)|DocMonospaced(HsDocid)|DocUnorderedList[HsDocid]|DocOrderedList[HsDocid]|DocDefList[(HsDocid,HsDocid)]|DocCodeBlock(HsDocid)|DocURLString|DocPicString|DocANameStringderiving(Eq,Show)typeLHsDocid=Located(HsDocid)#endifdataDocMarkupida=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}#if __GLASGOW_HASKELL__ >= 611dataHaddockModInfoname=HaddockModInfo{hmi_description::Maybe(HsDocname),hmi_portability::MaybeString,hmi_stability::MaybeString,hmi_maintainer::MaybeString}emptyHaddockModInfo::HaddockModInfoaemptyHaddockModInfo=HaddockModInfo{hmi_description=Nothing,hmi_portability=Nothing,hmi_stability=Nothing,hmi_maintainer=Nothing}#endif-- A monad which collects error messages, locally defined to avoid a dep on mtltypeErrMsg=StringnewtypeErrMsgMa=Writer{runWriter::(a,[ErrMsg])}instanceFunctorErrMsgMwherefmapf(Writer(a,msgs))=Writer(fa,msgs)instanceMonadErrMsgMwherereturna=Writer(a,[])m>>=k=Writer$let(a,w)=runWriterm(b,w')=runWriter(ka)in(b,w++w')tell::[ErrMsg]->ErrMsgM()tellw=Writer((),w)-- Exceptions-- | Haddock's own exception typedataHaddockException=HaddockExceptionStringderivingTypeableinstanceShowHaddockExceptionwhereshow(HaddockExceptionstr)=strthrowE::String->ainstanceExceptionHaddockExceptionthrowEstr=throw(HaddockExceptionstr)-- In "Haddock.Interface.Create", we need to gather-- @Haddock.Types.ErrMsg@s a lot, like @ErrMsgM@ does,-- but we can't just use @GhcT ErrMsgM@ because GhcT requires the-- transformed monad to be MonadIO.newtypeErrMsgGhca=WriterGhc{runWriterGhc::(Ghc(a,[ErrMsg]))}--instance MonadIO ErrMsgGhc where-- liftIO = WriterGhc . fmap (\a->(a,[])) liftIO--er, implementing GhcMonad involves annoying ExceptionMonad and--WarnLogMonad classes, so don't bother.liftGhcToErrMsgGhc::Ghca->ErrMsgGhcaliftGhcToErrMsgGhc=WriterGhc.fmap(\a->(a,[]))liftErrMsg::ErrMsgMa->ErrMsgGhcaliftErrMsg=WriterGhc.return.runWriter-- for now, use (liftErrMsg . tell) for this--tell :: [ErrMsg] -> ErrMsgGhc ()--tell msgs = WriterGhc $ return ( (), msgs )instanceFunctorErrMsgGhcwherefmapf(WriterGhcx)=WriterGhc(fmap(\(a,msgs)->(fa,msgs))x)instanceMonadErrMsgGhcwherereturna=WriterGhc(return(a,[]))m>>=k=WriterGhc$runWriterGhcm>>=\(a,msgs1)->fmap(\(b,msgs2)->(b,msgs1++msgs2))(runWriterGhc(ka))-- When HsDoc syntax is part of the Haddock codebase, we'll just-- declare a Functor instance.fmapHsDoc::(a->b)->HsDoca->HsDocbfmapHsDoc_DocEmpty=DocEmptyfmapHsDocf(DocAppendab)=DocAppend(fmapHsDocfa)(fmapHsDocfb)fmapHsDoc_(DocStrings)=DocStringsfmapHsDoc_(DocModules)=DocModulesfmapHsDoc_(DocURLs)=DocURLsfmapHsDoc_(DocPics)=DocPicsfmapHsDoc_(DocANames)=DocANamesfmapHsDocf(DocParagrapha)=DocParagraph(fmapHsDocfa)fmapHsDocf(DocEmphasisa)=DocEmphasis(fmapHsDocfa)fmapHsDocf(DocMonospaceda)=DocMonospaced(fmapHsDocfa)fmapHsDocf(DocCodeBlocka)=DocMonospaced(fmapHsDocfa)fmapHsDocf(DocIdentifiera)=DocIdentifier(mapfa)fmapHsDocf(DocOrderedLista)=DocOrderedList(map(fmapHsDocf)a)fmapHsDocf(DocUnorderedLista)=DocUnorderedList(map(fmapHsDocf)a)fmapHsDocf(DocDefLista)=DocDefList(map(\(b,c)->(fmapHsDocfb,fmapHsDocfc))a)