diff options
| -rw-r--r-- | haddock.cabal | 2 | ||||
| -rw-r--r-- | src/Documentation/Haddock.hs | 54 | ||||
| -rw-r--r-- | src/Haddock/Interface.hs | 13 | ||||
| -rw-r--r-- | src/Haddock/Types.hs | 90 | ||||
| -rw-r--r-- | tests/runtests.hs | 4 |
5 files changed, 100 insertions, 63 deletions
diff --git a/haddock.cabal b/haddock.cabal index b79b7b86..8cd2d835 100644 --- a/haddock.cabal +++ b/haddock.cabal @@ -131,6 +131,8 @@ library Documentation.Haddock other-modules: + Haddock.Lex + Haddock.Parse Haddock.Types Haddock.InterfaceFile Haddock.Utils diff --git a/src/Documentation/Haddock.hs b/src/Documentation/Haddock.hs index 13bbc543..d10c89df 100644 --- a/src/Documentation/Haddock.hs +++ b/src/Documentation/Haddock.hs @@ -1,22 +1,60 @@ +----------------------------------------------------------------------------- +-- | +-- Module : Documentation.Haddock +-- Copyright : (c) David Waern 2010 +-- License : BSD-like -- --- Haddock - A Haskell Documentation Tool --- --- (c) Simon Marlow 2003 +-- Maintainer : haddock@projects.haskellorg +-- Stability : experimental +-- Portability : portable -- +-- 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 ( + + -- * Interface + Interface(..), + InstalledInterface(..), + createInterfaces, + + -- * Export items & declarations + ExportItem(..), + DeclInfo, + DocForDecl, + FnArgsDoc, + + -- * Hyperlinking + LinkEnv, + DocName(..), + docNameOcc, + + -- * Instances + DocInstance, + InstHead(..), + + -- * Documentation comments + Doc(..), + DocMarkup(..), + + -- * Interface Files + -- | (.haddock files) + InterfaceFile(..), readInterfaceFile, nameCacheFromGhc, freshNameCache, NameCacheAccessor, - InterfaceFile(..), - LinkEnv, - InstalledInterface(..), - DocName(..), - docNameOcc + + -- * Flags and options + Flag(..), + DocOption(..) + ) where import Haddock.InterfaceFile +import Haddock.Interface import Haddock.Types +import Haddock.Options diff --git a/src/Haddock/Interface.hs b/src/Haddock/Interface.hs index 8816b294..ffe2ae71 100644 --- a/src/Haddock/Interface.hs +++ b/src/Haddock/Interface.hs @@ -40,10 +40,15 @@ import Digraph import HscTypes --- | Turn a topologically sorted list of module names/filenames into interfaces. Also --- return the home link environment created in the process. -createInterfaces :: Verbosity -> [String] -> [Flag] -> [InterfaceFile] - -> Ghc ([Interface], LinkEnv) +-- | Create 'Interface' structures by typechecking the list of modules +-- using the GHC API and processing the resulting syntax trees. +createInterfaces + :: 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 createInterfaces verbosity modules flags extIfaces = do -- part 1, create interfaces let instIfaceMap = Map.fromList [ (instMod iface, iface) | ext <- extIfaces diff --git a/src/Haddock/Types.hs b/src/Haddock/Types.hs index f3b35540..f65f88e9 100644 --- a/src/Haddock/Types.hs +++ b/src/Haddock/Types.hs @@ -36,6 +36,8 @@ import Test.QuickCheck -- convenient short-hands type Decl = LHsDecl Name + +-- | An instance head that may have documentation. type DocInstance name = (InstHead name, Maybe (Doc name)) @@ -52,14 +54,13 @@ noDocForDecl = (Nothing, Map.empty) type DeclInfo = (Decl, DocForDecl Name, [(Name, DocForDecl Name)]) --- | A 'DocName' identifies something that may have documentation. The 'Module' --- argument specifies where we prefer to link to in the documentation. It may --- be different than the original module. -data DocName = Documented Name Module | Undocumented Name - deriving Eq +-- | An extension of 'Name' that may contain the preferred place to link to in +-- the documentation. +data DocName = Documented Name Module | Undocumented Name deriving Eq +-- TODO: simplify to data DocName = DocName Name (Maybe Module) --- | The 'OccName' belonging to this name +-- | The 'OccName' of this name. docNameOcc :: DocName -> OccName docNameOcc = nameOccName . getName @@ -70,6 +71,7 @@ instance NamedThing DocName where {-! for DocOption derive: Binary !-} +-- | Source-level options for controlling the documentation. data DocOption = OptHide -- ^ This module should not appear in the docs | OptPrune @@ -134,6 +136,8 @@ type InstHead name = ([HsPred name], name, [HsType name]) type ModuleMap = Map Module Interface type InstIfaceMap = Map Module InstalledInterface type DocMap = Map Name (Doc DocName) + +-- | An environment used to create hyper-linked syntax. type LinkEnv = Map Name Module @@ -156,36 +160,37 @@ data GhcModule = GhcModule { } --- | 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 +-- | 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. data Interface = Interface { - -- | The module represented by this interface + -- | The module represented by this interface. ifaceMod :: Module, - -- | The original filename for this module + -- | Original file name of the module. ifaceOrigFilename :: FilePath, - -- | Textual information about the module + -- | Textual information about the module. ifaceInfo :: !(HaddockModInfo Name), - -- | The documentation header for this module + -- | Documentation header. ifaceDoc :: !(Maybe (Doc Name)), - -- | The renamed documentation header for this module + -- | Documentation header with link information. ifaceRnDoc :: Maybe (Doc DocName), - -- | The Haddock options for this module (prune, ignore-exports, etc) + -- | 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. + -- | 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 :: Map Name DeclInfo, - -- | Everything declared in the module (including subordinates) that has docs + -- | Documentation of declarations originating from the module (including + -- subordinates). ifaceRnDocMap :: Map Name (DocForDecl DocName), ifaceSubMap :: Map Name [Name], @@ -193,61 +198,48 @@ data Interface = Interface { ifaceExportItems :: ![ExportItem Name], ifaceRnExportItems :: [ExportItem DocName], - -- | All names defined in this module + -- | All names defined in the module. ifaceLocals :: ![Name], - -- | All names exported by this module + -- | All names exported by the module. ifaceExports :: ![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. + -- | All \"visible\" names exported by the module. + -- A visible name is a name that will show up in the documentation of the + -- module. ifaceVisibleExports :: ![Name], - -- | The instances exported by this module + -- | Instances exported by the module. ifaceInstances :: ![Instance], - -- | Docs for instances defined in this module + -- | Documentation of instances defined in the module. ifaceInstanceDocMap :: Map Name (Doc Name) } --- | A smaller version of 'Interface' that we can get from the Haddock --- interface files. +-- | A smaller version of 'Interface' that can be created from Haddock's +-- interface files ('InterfaceFile'). data InstalledInterface = InstalledInterface { - -- | The module represented by this interface + -- | The module represented by this interface. instMod :: Module, - -- | Textual information about the module + -- | Textual information about the module. instInfo :: HaddockModInfo Name, - -- | Everything declared in the module (including subordinates) that has docs + -- | Documentation of declarations originating from the module (including + -- subordinates). instDocMap :: Map Name (DocForDecl Name), - -- | All names exported by this module + -- | All names exported by this module. instExports :: [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. + -- | All \"visible\" names exported by the module. + -- A visible name is a name that will show up in the documentation of the + -- module. instVisibleExports :: [Name], - -- | The Haddock options for this module (prune, ignore-exports, etc) + -- | Haddock options for this module (prune, ignore-exports, etc). instOptions :: [DocOption], instSubMap :: Map Name [Name] diff --git a/tests/runtests.hs b/tests/runtests.hs index aaf5c3dd..2f2e96c6 100644 --- a/tests/runtests.hs +++ b/tests/runtests.hs @@ -75,9 +75,9 @@ test = do putStrLn "" libdir <- rawSystemStdout normal "../dist/build/haddock/haddock" ["--print-ghc-libdir"] - let basepath = init libdir ++ "/../../share/doc/ghc/html/libraries/base/" + let basepath = init libdir ++ "/../../share/doc/ghc/html/libraries/base-4.2.0.0/" let base = "-i " ++ basepath ++ "," ++ basepath ++ "base.haddock" - let processpath = init libdir ++ "/../../share/doc/ghc/html/libraries/process/" + let processpath = init libdir ++ "/../../share/doc/ghc/html/libraries/process-1.0.1.2/" let process = "-i " ++ processpath ++ "," ++ processpath ++ "process.haddock" putStrLn "Running tests..." |