diff --git a/CHANGES b/CHANGES --- a/CHANGES +++ b/CHANGES @@ -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 diff --git a/doc/invoking.rst b/doc/invoking.rst --- a/doc/invoking.rst +++ b/doc/invoking.rst @@ -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 diff --git a/doc/markup.rst b/doc/markup.rst --- a/doc/markup.rst +++ b/doc/markup.rst @@ -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 `__. Anchors ~~~~~~~ diff --git a/haddock-api/src/Documentation/Haddock.hs b/haddock-api/src/Documentation/Haddock.hs --- a/haddock-api/src/Documentation/Haddock.hs +++ b/haddock-api/src/Documentation/Haddock.hs @@ -16,6 +16,7 @@ -- * Interface Interface(..), InstalledInterface(..), + toInstalledIface, createInterfaces, processModules, @@ -34,6 +35,7 @@ -- * Documentation comments Doc, + MDoc, DocH(..), Example(..), Hyperlink(..), diff --git a/haddock-api/src/Haddock.hs b/haddock-api/src/Haddock.hs --- a/haddock-api/src/Haddock.hs +++ b/haddock-api/src/Haddock.hs @@ -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 diff --git a/haddock-api/src/Haddock/Backends/Hyperlinker/Parser.hs b/haddock-api/src/Haddock/Backends/Hyperlinker/Parser.hs --- a/haddock-api/src/Haddock/Backends/Hyperlinker/Parser.hs +++ b/haddock-api/src/Haddock/Backends/Hyperlinker/Parser.hs @@ -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 diff --git a/haddock-api/src/Haddock/Backends/Hyperlinker/Types.hs b/haddock-api/src/Haddock/Backends/Hyperlinker/Types.hs --- a/haddock-api/src/Haddock/Backends/Hyperlinker/Types.hs +++ b/haddock-api/src/Haddock/Backends/Hyperlinker/Types.hs @@ -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 diff --git a/haddock-api/src/Haddock/Backends/Xhtml.hs b/haddock-api/src/Haddock/Backends/Xhtml.hs --- a/haddock-api/src/Haddock/Backends/Xhtml.hs +++ b/haddock-api/src/Haddock/Backends/Xhtml.hs @@ -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 diff --git a/haddock-api/src/Haddock/Backends/Xhtml/Utils.hs b/haddock-api/src/Haddock/Backends/Xhtml/Utils.hs --- a/haddock-api/src/Haddock/Backends/Xhtml/Utils.hs +++ b/haddock-api/src/Haddock/Backends/Xhtml/Utils.hs @@ -75,8 +75,7 @@ case span_ of RealSrcSpan span__ -> show $ srcSpanStartLine span__ - UnhelpfulSpan _ -> - error "spliceURL UnhelpfulSpan" + UnhelpfulSpan _ -> "" run "" = "" run ('%':'M':rest) = mdl ++ run rest diff --git a/haddock-api/src/Haddock/Convert.hs b/haddock-api/src/Haddock/Convert.hs --- a/haddock-api/src/Haddock/Convert.hs +++ b/haddock-api/src/Haddock/Convert.hs @@ -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) diff --git a/haddock-api/src/Haddock/Interface/Create.hs b/haddock-api/src/Haddock/Interface/Create.hs --- a/haddock-api/src/Haddock/Interface/Create.hs +++ b/haddock-api/src/Haddock/Interface/Create.hs @@ -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 diff --git a/haddock-api/src/Haddock/Interface/ParseModuleHeader.hs b/haddock-api/src/Haddock/Interface/ParseModuleHeader.hs --- a/haddock-api/src/Haddock/Interface/ParseModuleHeader.hs +++ b/haddock-api/src/Haddock/Interface/ParseModuleHeader.hs @@ -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 diff --git a/haddock-api/src/Haddock/Types.hs b/haddock-api/src/Haddock/Types.hs --- a/haddock-api/src/Haddock/Types.hs +++ b/haddock-api/src/Haddock/Types.hs @@ -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` () diff --git a/haddock-api/src/Haddock/Utils.hs b/haddock-api/src/Haddock/Utils.hs --- a/haddock-api/src/Haddock/Utils.hs +++ b/haddock-api/src/Haddock/Utils.hs @@ -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" ------------------------------------------------------------------------------- diff --git a/haddock-library/src/Documentation/Haddock/Parser/Monad.hs b/haddock-library/src/Documentation/Haddock/Parser/Monad.hs --- a/haddock-library/src/Documentation/Haddock/Parser/Monad.hs +++ b/haddock-library/src/Documentation/Haddock/Parser/Monad.hs @@ -42,7 +42,7 @@ import Documentation.Haddock.Types (Version) -data ParserState = ParserState { +newtype ParserState = ParserState { parserStateSince :: Maybe Version } deriving (Eq, Show) diff --git a/haddock.cabal b/haddock.cabal --- a/haddock.cabal +++ b/haddock.cabal @@ -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 , Mateusz Kowalczyk +maintainer: Alex Biehl , Simon Hengel , Mateusz Kowalczyk 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 diff --git a/html-test/ref/Bug280.html b/html-test/ref/Bug280.html new file mode 100644 --- /dev/null +++ b/html-test/ref/Bug280.html @@ -0,0 +1,81 @@ + +Bug280
CopyrightFoo
Bar
Baz
Safe HaskellSafe

Bug280

Description

The module description

Documentation

x :: [Char] #

diff --git a/html-test/ref/Test.html b/html-test/ref/Test.html --- a/html-test/ref/Test.html +++ b/html-test/ref/Test.html @@ -33,7 +33,7 @@ >
- - - - - - - - - - - - - - diff --git a/html-test/src/Bug280.hs b/html-test/src/Bug280.hs new file mode 100644 --- /dev/null +++ b/html-test/src/Bug280.hs @@ -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 = ""
Copyright(c) Simon Marlow 2002