haddock 2.17.2 → 2.17.4

raw patch · 20 files changed

+202/−114 lines, 20 filesdep ~basedep ~haddock-apidep ~haddock-testnew-uploader

Dependency ranges changed: base, haddock-api, haddock-test

Files

• CHANGES +18/−0
• doc/invoking.rst +2/−6
• doc/markup.rst +16/−1
• haddock-api/src/Documentation/Haddock.hs +2/−0
• haddock-api/src/Haddock.hs +1/−1
• haddock-api/src/Haddock/Backends/Hyperlinker/Parser.hs +11/−1
• haddock-api/src/Haddock/Backends/Hyperlinker/Types.hs +3/−0
• haddock-api/src/Haddock/Backends/Xhtml.hs +17/−43
• haddock-api/src/Haddock/Backends/Xhtml/Utils.hs +1/−2
• haddock-api/src/Haddock/Convert.hs +3/−1
• haddock-api/src/Haddock/Interface/Create.hs +13/−6
• haddock-api/src/Haddock/Interface/ParseModuleHeader.hs +1/−1
• haddock-api/src/Haddock/Types.hs +6/−2
• haddock-api/src/Haddock/Utils.hs +2/−10
• haddock-library/src/Documentation/Haddock/Parser/Monad.hs +1/−1
• haddock.cabal +12/−8
• html-test/ref/Bug280.html +81/−0
• html-test/ref/Test.html +1/−1
• html-test/ref/frames.html +0/−30
• html-test/src/Bug280.hs +11/−0

@@ -1,3 +1,21 @@+Changes in version 2.17.4++ * Fix 'internal error: links: UnhelpfulSpan' (#554, #565)++ * Hyperlink backend knows about `DataKinds` (#510)++ * Fix rendering of class methods for `Eq` and `Ord` (#549)++ * Export `MDoc` and `toInstalledIface` from `Haddock.Types`++Changes in version 2.17.3.1++ * Disable `NFData` instances for GHC types when GHC >= 8.0.2 (#537)++Changes in version 2.17.3++ * Remove framed view of the HTML documentation+ Changes in version 2.17.2   * Fix portability of documentation building within GHC

@@ -100,7 +100,7 @@      ``module.html``; ``mini_module.html``         An HTML page for each module, and a "mini" page for each used-        when viewing in frames.+        when viewing their synopsis.      ``index.html``         The top level page of the documentation: lists the modules@@ -111,17 +111,13 @@         The alphabetic index, possibly split into multiple pages if big         enough. -    ``frames.html``-        The top level document when viewing in frames.-     ``some.css``; ``etc...``         Files needed for the themes used. Specify your themes using the         :option:`--theme` option.      ``haddock-util.js``         Some JavaScript utilities used to implement some of the dynamic-        features like collapsible sections, and switching to frames-        view.+        features like collapsible sections.  .. option:: --latex 

@@ -501,7 +501,7 @@ ~~~~~~~~~~~~~~~~~~  The following characters have special meanings in documentation-comments: ``\\``, ``/``, ``'``, ``\```, ``"``, ``@``, ``<``. To insert a+comments: ``\\``, ``/``, ``'``, ``\```, ``"``, ``@``, ``<``, ``$``. To insert a literal occurrence of one of these special characters, precede it with a backslash (``\\``). @@ -798,6 +798,21 @@ If the output format supports it, the image will be rendered inside the documentation. The image description is used as relpacement text and/or image title.++Mathematics / LaTeX+~~~~~~~~~~~~~~~~~~~++Haddock supports LaTeX syntax for rendering mathematical notation. The+delimiters are ``\[...\]`` for displayed mathematics and ``\(...\)``+for in-line mathematics. An example looks like this: ::++  \[+  f(a) = \frac{1}{2\pi i}\oint_\gamma \frac{f(z)}{z-a}\,\mathrm{d}z+  \]++If the output format supports it, the mathematics will be rendered+inside the documentation. For example, the HTML backend will display+the mathematics via `MathJax <https://www.mathjax.org>`__.  Anchors ~~~~~~~

@@ -16,6 +16,7 @@   -- * Interface   Interface(..),   InstalledInterface(..),+  toInstalledIface,   createInterfaces,   processModules, @@ -34,6 +35,7 @@    -- * Documentation comments   Doc,+  MDoc,   DocH(..),   Example(..),   Hyperlink(..),

@@ -336,7 +336,7 @@     ppLaTeX title pkgStr visibleIfaces odir (fmap _doc prologue) opt_latex_style                   libDir -  when (Flag_HyperlinkedSource `elem` flags) $ do+  when (Flag_HyperlinkedSource `elem` flags && not (null ifaces)) $ do     ppHyperlinkedSource odir libDir opt_source_css pretty srcMap ifaces  -- | From GHC 7.10, this function has a potential to crash with a

@@ -31,12 +31,20 @@ chunk str     | "--" `isPrefixOf` str = chunk' $ spanToNewline str     | "{-" `isPrefixOf` str = chunk' $ chunkComment 0 str-    | otherwise = case lex str of+    | otherwise = case lex' str of         (tok:_) -> chunk' tok         [] -> [str]   where     chunk' (c, rest) = c:(chunk rest) +-- | A bit better lexer then the default, i.e. handles DataKinds quotes+lex' :: ReadS String+lex' ('\'' : '\'' : rest)              = [("''", rest)]+lex' str@('\'' : '\\' : _ : '\'' : _)  = lex str+lex' str@('\'' : _ : '\'' : _)         = lex str+lex' ('\'' : rest)                     = [("'", rest)]+lex' str                               = lex str+ -- | Split input to "first line" string and the rest of it. -- -- Ideally, this should be done simply with @'break' (== '\n')@. However,@@ -124,6 +132,8 @@     | "--" `isPrefixOf` str = TkComment     | "{-#" `isPrefixOf` str = TkPragma     | "{-" `isPrefixOf` str = TkComment+classify "''" = TkSpecial+classify "'"  = TkSpecial classify str@(c:_)     | isSpace c = TkSpace     | isDigit c = TkNumber

@@ -12,16 +12,19 @@     , tkValue :: String     , tkSpan :: Span     }+    deriving (Show)  data Position = Position     { posRow :: !Int     , posCol :: !Int     }+    deriving (Show)  data Span = Span     { spStart :: Position     , spEnd :: Position     }+    deriving (Show)  data TokenType     = TkIdentifier

@@ -35,15 +35,14 @@ import Haddock.GhcUtils  import Control.Monad         ( when, unless )-import Data.Char             ( toUpper )-import Data.List             ( sortBy, groupBy, intercalate, isPrefixOf )+import Data.Char             ( toUpper, isSpace )+import Data.List             ( sortBy, intercalate, isPrefixOf, intersperse ) import Data.Maybe import System.FilePath hiding ( (</>) ) import System.Directory import Data.Map              ( Map ) import qualified Data.Map as Map hiding ( Map ) import qualified Data.Set as Set hiding ( Set )-import Data.Function import Data.Ord              ( comparing )  import DynFlags (Language(..))@@ -105,7 +104,8 @@     copyCssFile f = copyFile f (combine odir (takeFileName f))     copyLibFile f = copyFile (joinPath [libhtmldir, f]) (joinPath [odir, f])   mapM_ copyCssFile (cssFiles themes)-  mapM_ copyLibFile [ jsFile, framesFile ]+  copyLibFile jsFile+  return ()   headHtml :: String -> Maybe String -> Themes -> Maybe String -> Html@@ -172,7 +172,7 @@            maybe_source_url maybe_wiki_url            maybe_contents_url maybe_index_url            pageContent =-  body << [+  body ! [theclass "no-frame"] << [     divPackageHeader << [       unordList (catMaybes [         srcButton maybe_source_url iface,@@ -201,8 +201,7 @@         field info >>= \a -> return (th << fieldName <-> td << a)        entries :: [HtmlTable]-      entries = mapMaybe doOneEntry [-          ("Copyright",hmi_copyright),+      entries = maybeToList copyrightsTable ++ mapMaybe doOneEntry [           ("License",hmi_license),           ("Maintainer",hmi_maintainer),           ("Stability",hmi_stability),@@ -216,6 +215,14 @@             Just Haskell98 -> Just "Haskell98"             Just Haskell2010 -> Just "Haskell2010" +          multilineRow :: String -> [String] -> HtmlTable+          multilineRow title xs = (th ! [valign "top"]) << title <-> td << (toLines xs)+            where toLines = mconcat . intersperse br . map toHtml++          copyrightsTable :: Maybe HtmlTable+          copyrightsTable = fmap (multilineRow "Copyright" . split) (hmi_copyright info)+            where split = map (trim . filter (/= ',')) . lines+           extsForm             | OptShowExtensions `elem` ifaceOptions iface =               let fs = map (dropOpt . show) (hmi_extensions info)@@ -268,10 +275,7 @@   createDirectoryIfMissing True odir   writeFile (joinPath [odir, contentsHtmlFile]) (renderToString debug html) -  -- XXX: think of a better place for this?-  ppHtmlContentsFrame odir doctitle themes mathjax_url ifaces debug - ppPrologue :: Qualification -> String -> Maybe (MDoc GHC.RdrName) -> Html ppPrologue _ _ Nothing = noHtml ppPrologue qual title (Just doc) =@@ -321,40 +325,7 @@     subtree = mkNodeList qual (s:ss) p ts ! collapseSection p True ""  --- | Turn a module tree into a flat list of full module names.  E.g.,--- @---  A---  +-B---  +-C--- @--- becomes--- @["A", "A.B", "A.B.C"]@-flatModuleTree :: [InstalledInterface] -> [Html]-flatModuleTree ifaces =-    map (uncurry ppModule' . head)-            . groupBy ((==) `on` fst)-            . sortBy (comparing fst)-            $ mods-  where-    mods = [ (moduleString mdl, mdl) | mdl <- map instMod ifaces ]-    ppModule' txt mdl =-      anchor ! [href (moduleHtmlFile mdl), target mainFrameName]-        << toHtml txt --ppHtmlContentsFrame :: FilePath -> String -> Themes -> Maybe String-  -> [InstalledInterface] -> Bool -> IO ()-ppHtmlContentsFrame odir doctitle themes maybe_mathjax_url ifaces debug = do-  let mods = flatModuleTree ifaces-      html =-        headHtml doctitle Nothing themes maybe_mathjax_url +++-        miniBody << divModuleList <<-          (sectionName << "Modules" +++-           ulist << [ li ! [theclass "module"] << m | m <- mods ])-  createDirectoryIfMissing True odir-  writeFile (joinPath [odir, frameIndexHtmlFile]) (renderToString debug html)-- -------------------------------------------------------------------------------- -- * Generate the index --------------------------------------------------------------------------------@@ -684,6 +655,9 @@ processDecl True = Just processDecl False = Just . divTopDecl +trim :: String -> String+trim = f . f+  where f = reverse . dropWhile isSpace  processDeclOneLiner :: Bool -> Html -> Maybe Html processDeclOneLiner True = Just

@@ -75,8 +75,7 @@       case span_ of       RealSrcSpan span__ ->         show $ srcSpanStartLine span__-      UnhelpfulSpan _ ->-        error "spliceURL UnhelpfulSpan"+      UnhelpfulSpan _ -> ""    run "" = ""   run ('%':'M':rest) = mdl  ++ run rest

@@ -82,7 +82,7 @@                         (map (noLoc . getName) l, map (noLoc . getName) r) ) $                          snd $ classTvsFds cl          , tcdSigs = noLoc (MinimalSig mempty . noLoc . fmap noLoc $ classMinimalDef cl) :-                      map (noLoc . synifyIdSig DeleteTopLevelQuantification)+                      map (noLoc . synifyTcIdSig DeleteTopLevelQuantification)                         (classMethods cl)          , tcdMeths = emptyBag --ignore default method definitions, they don't affect signature          -- class associated-types are a subset of TyCon:@@ -317,6 +317,8 @@ synifyIdSig :: SynifyTypeState -> Id -> Sig Name synifyIdSig s i = TypeSig [synifyName i] (synifySigWcType s (varType i)) +synifyTcIdSig :: SynifyTypeState -> Id -> Sig Name+synifyTcIdSig s i = ClassOpSig False [synifyName i] (synifySigType s (varType i))  synifyCtx :: [PredType] -> LHsContext Name synifyCtx = noLoc . map (synifyType WithinType)

@@ -36,7 +36,6 @@ import Control.DeepSeq import Control.Monad import Data.Function (on)-import qualified Data.Foldable as F  import qualified Packages import qualified Module@@ -50,7 +49,7 @@ import FastString (concatFS) import BasicTypes ( StringLiteral(..) ) import qualified Outputable as O-import HsDecls ( gadtDeclDetails,getConDetails )+import HsDecls ( getConDetails )  -- | Use a 'TypecheckedModule' to produce an 'Interface'. -- To do this, we need access to already processed modules in the topological@@ -784,13 +783,21 @@   | otherwise  =     case unLoc decl of       TyClD d@ClassDecl {} ->-        let matches = [ sig | sig <- tcdSigs d, name `elem` sigName sig,-                        isTypeLSig sig ] -- TODO: document fixity+        let matches = [ lsig+                      | lsig <- tcdSigs d+                      , ClassOpSig False _ _ <- pure $ unLoc lsig+                        -- Note: exclude `default` declarations (see #505)+                      , name `elem` sigName lsig+                      ]+            -- TODO: document fixity         in case matches of           [s0] -> let (n, tyvar_names) = (tcdName d, tyClDeclTyVars d)                       L pos sig = addClassContext n tyvar_names s0                   in L pos (SigD sig)-          _ -> error "internal: extractDecl (ClassDecl)"+          _ -> O.pprPanic "extractDecl" (O.text "Ambiguous decl for" O.<+> O.ppr name O.<+> O.text "in class:"+                                         O.$$ O.nest 4 (O.ppr d)+                                         O.$$ O.text "Matches:"+                                         O.$$ O.nest 4 (O.ppr matches))       TyClD d@DataDecl {} ->         let (n, tyvar_tys) = (tcdName d, lHsQTyVarsToTypes (tyClDeclTyVars d))         in SigD <$> extractRecSel name mdl n tyvar_tys (dd_cons (tcdDataDefn d))@@ -825,7 +832,7 @@   matching_fields flds = [ (l,f) | f@(L _ (ConDeclField ns _ _)) <- flds                                  , L l n <- ns, selectorFieldOcc n == nm ]   data_ty-    -- | ResTyGADT _ ty <- con_res con = ty+    -- ResTyGADT _ ty <- con_res con = ty     | ConDeclGADT{} <- con = hsib_body $ con_type con     | otherwise = foldl' (\x y -> noLoc (HsAppTy x y)) (noLoc (HsTyVar (noLoc t))) tvs 

@@ -76,7 +76,7 @@ parseKey key toParse0 =    do       let-         (spaces0,toParse1) = extractLeadingSpaces toParse0+         (spaces0,toParse1) = extractLeadingSpaces (dropWhile (`elem` ['\r', '\n']) toParse0)           indentation = spaces0       afterKey0 <- extractPrefix key toParse1

@@ -1,4 +1,6 @@-{-# LANGUAGE DeriveDataTypeable, DeriveFunctor, DeriveFoldable, DeriveTraversable, StandaloneDeriving, TypeFamilies, RecordWildCards #-}+{-# LANGUAGE CPP #-}+{-# LANGUAGE DeriveDataTypeable, DeriveFunctor, DeriveFoldable, DeriveTraversable, StandaloneDeriving #-}+{-# LANGUAGE TypeFamilies, RecordWildCards #-} {-# OPTIONS_GHC -fno-warn-orphans #-} ----------------------------------------------------------------------------- -- |@@ -447,10 +449,12 @@     DocExamples a             -> a `deepseq` ()     DocHeader a               -> a `deepseq` () -+#if !MIN_VERSION_ghc(8,0,2)+-- These were added to GHC itself in 8.0.2 instance NFData Name where rnf x = seq x () instance NFData OccName where rnf x = seq x () instance NFData ModuleName where rnf x = seq x ()+#endif  instance NFData id => NFData (Header id) where   rnf (Header a b) = a `deepseq` b `deepseq` ()

@@ -21,10 +21,9 @@   -- * Filename utilities   moduleHtmlFile, moduleHtmlFile',   contentsHtmlFile, indexHtmlFile,-  frameIndexHtmlFile,   moduleIndexFrameName, mainFrameName, synopsisFrameName,   subIndexHtmlFile,-  jsFile, framesFile,+  jsFile,    -- * Anchor and URL utilities   moduleNameUrl, moduleNameUrl', moduleUrl,@@ -262,13 +261,7 @@ indexHtmlFile = "doc-index.html"  --- | The name of the module index file to be displayed inside a frame.--- Modules are display in full, but without indentation.  Clicking opens in--- the main window.-frameIndexHtmlFile :: String-frameIndexHtmlFile = "index-frames.html" - moduleIndexFrameName, mainFrameName, synopsisFrameName :: String moduleIndexFrameName = "modules" mainFrameName = "main"@@ -333,9 +326,8 @@ -------------------------------------------------------------------------------  -jsFile, framesFile :: String+jsFile :: String jsFile    = "haddock-util.js"-framesFile = "frames.html"   -------------------------------------------------------------------------------

@@ -42,7 +42,7 @@  import           Documentation.Haddock.Types (Version) -data ParserState = ParserState {+newtype ParserState = ParserState {   parserStateSince :: Maybe Version } deriving (Eq, Show) 

@@ -1,12 +1,12 @@ name:                 haddock-version:              2.17.2+version:              2.17.4 synopsis:             A documentation-generation tool for Haskell libraries description:          Haddock is a documentation-generation tool for Haskell                       libraries license:              BSD3 license-file:         LICENSE author:               Simon Marlow, David Waern-maintainer:           Simon Hengel <sol@typeful.net>, Mateusz Kowalczyk <fuuzetsu@fuuzetsu.co.uk>+maintainer:           Alex Biehl <alexbiehl@gmail.com>, Simon Hengel <sol@typeful.net>, Mateusz Kowalczyk <fuuzetsu@fuuzetsu.co.uk> homepage:             http://www.haskell.org/haddock/ bug-reports:          https://github.com/haskell/haddock/issues copyright:            (c) Simon Marlow, David Waern@@ -42,8 +42,10 @@   hs-source-dirs:       driver   ghc-options:          -funbox-strict-fields -Wall -fwarn-tabs -O2 -threaded +  -- haddock typically only supports a single GHC major version   build-depends:-    base >= 4.3 && < 4.10+    base == 4.9.*+   if flag(in-ghc-tree)     hs-source-dirs: haddock-api/src, haddock-library/vendor/attoparsec-0.12.1.1, haddock-library/src     cpp-options: -DIN_GHC_TREE@@ -119,7 +121,9 @@       Haddock.Syb       Haddock.Convert   else-    build-depends:  haddock-api == 2.17.*+    -- in order for haddock's advertised version number to have proper meaning,+    -- we pin down to a single haddock-api version.+    build-depends:  haddock-api == 2.17.4  test-suite driver-test   type:             exitcode-stdio-1.0@@ -133,14 +137,14 @@   default-language: Haskell2010   main-is:          Main.hs   hs-source-dirs:   html-test-  build-depends:    base, filepath, haddock-test+  build-depends:    base, filepath, haddock-test == 0.0.1  test-suite hypsrc-test   type:             exitcode-stdio-1.0   default-language: Haskell2010   main-is:          Main.hs   hs-source-dirs:   hypsrc-test-  build-depends:    base, filepath, haddock-test+  build-depends:    base, filepath, haddock-test == 0.0.1   ghc-options:      -Wall -fwarn-tabs  test-suite latex-test@@ -148,14 +152,14 @@   default-language: Haskell2010   main-is:          Main.hs   hs-source-dirs:   latex-test-  build-depends:    base, filepath, haddock-test+  build-depends:    base, filepath, haddock-test == 0.0.1  test-suite hoogle-test   type:             exitcode-stdio-1.0   default-language: Haskell2010   main-is:          Main.hs   hs-source-dirs:   hoogle-test-  build-depends:    base, filepath, haddock-test+  build-depends:    base, filepath, haddock-test == 0.0.1  source-repository head   type:     git

@@ -0,0 +1,81 @@+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">+<html xmlns="http://www.w3.org/1999/xhtml"+><head+  ><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"+     /><title+    >Bug280</title+    ><link href="#" rel="stylesheet" type="text/css" title="Ocean"+     /><script src="haddock-util.js" type="text/javascript"+    ></script+    ><script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"+    ></script+    ><script type="text/javascript"+    >//<![CDATA[+window.onload = function () {pageLoad();setSynopsis("mini_Bug280.html");};+//]]>+</script+    ></head+  ><body+  ><div id="package-header"+    ><ul class="links" id="page-menu"+      ><li+	><a href="#"+	  >Contents</a+	  ></li+	><li+	><a href="#"+	  >Index</a+	  ></li+	></ul+      ><p class="caption empty"+      >&nbsp;</p+      ></div+    ><div id="content"+    ><div id="module-header"+      ><table class="info"+	><tr+	  ><th valign="top"+	    >Copyright</th+	    ><td+	    >Foo<br+         />Bar<br+         />Baz</td+	    ></tr+	  ><tr+	  ><th+	    >Safe Haskell</th+	    ><td+	    >Safe</td+	    ></tr+	  ></table+	><p class="caption"+	>Bug280</p+	></div+      ><div id="description"+      ><p class="caption"+	>Description</p+	><div class="doc"+		><p+		>The module description</p+		></div+	></div+      ><div id="interface"+      ><h1+	>Documentation</h1+	><div class="top"+	><p class="src"+	  ><a id="v:x" class="def"+	    >x</a+	    > :: [<a href="#"+	    >Char</a+	    >] <a href="#" class="selflink"+	    >#</a+	    ></p+	  ></div+	></div+      ></div+    ><div id="footer"+    ></div+    ></body+  ></html+>

@@ -33,7 +33,7 @@     ><div id="module-header"       ><table class="info" 	><tr-	  ><th+	  ><th valign="top" 	    >Copyright</th 	    ><td 	    >(c) Simon Marlow 2002</td

@@ -1,30 +0,0 @@-<!DOCTYPE html-     PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN"-     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">-<html xmlns="http://www.w3.org/1999/xhtml">-<head>-<title></title>-<script src="haddock-util.js" type="text/javascript"></script>-<script type="text/javascript"><!---/*--  The synopsis frame needs to be updated using javascript, so we hide-  it by default and only show it if javascript is enabled.--  TODO: provide some means to disable it.-*/-function load() {-  var d = document.getElementById("inner-fs");-  d.rows = "50%,50%";-  postReframe();-}---></script>-</head>-<frameset id="outer-fs" cols="25%,75%" onload="load()">-  <frameset id="inner-fs" rows="100%,0%">-    <frame src="index-frames.html" name="modules" />-    <frame src="" name="synopsis" />-  </frameset>-  <frame src="index.html" name="main" />-</frameset>-</html>

@@ -0,0 +1,11 @@+{-|+Copyright: Foo,+           Bar,+           Baz++The module description+-}+-- The module header can start with newlines. They are not taken into account for the indentation level+module Bug280 where++x = ""