aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--.github/workflows/ci.yml7
-rw-r--r--README.md10
-rw-r--r--doc/common-errors.rst19
-rw-r--r--doc/index.rst1
-rw-r--r--doc/intro.rst93
-rw-r--r--doc/markup.rst45
-rw-r--r--haddock-api/haddock-api.cabal11
-rw-r--r--haddock-api/src/Haddock/Backends/Hyperlinker.hs1
-rw-r--r--haddock-api/src/Haddock/Convert.hs1
-rw-r--r--haddock-api/src/Haddock/Interface/Rename.hs4
-rw-r--r--haddock-library/haddock-library.cabal13
-rw-r--r--haddock-test/src/Test/Haddock/Config.hs2
-rw-r--r--haddock.cabal2
-rw-r--r--html-test/ref/Instances.html8
14 files changed, 110 insertions, 107 deletions
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c2aa9f3c..dafcdc74 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -13,7 +13,7 @@ jobs:
strategy:
matrix:
os: [ubuntu-latest]
- cabal: ["3.4.0.0"]
+ cabal: ["3.6"]
ghc:
- "head"
@@ -41,12 +41,11 @@ jobs:
cabal freeze
- uses: actions/cache@v2
- name: Cache ~/.cabal/store and .ghcup
+ name: Cache ~/.cabal/store
with:
path: |
${{ steps.setup-haskell-cabal.outputs.cabal-store }}
- .ghcup
- key: ${{ runner.os }}
+ key: ${{ runner.os }}-${{ matrix.ghc }}-${{ hashFiles('cabal.project.freeze') }}
- name: Build
run: |
diff --git a/README.md b/README.md
index 69763a52..530e752d 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
Haddock is the standard tool for generating documentation from Haskell code.
Full documentation about Haddock itself can be found in the `doc/` subdirectory,
-in [reStructedText format][ReST] format.
+in [reStructuredText][reST] format.
## Project overview
@@ -25,10 +25,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) to see how to make contributions to the
project.
-[CI page]: https://travis-ci.org/haskell/haddock
-[CI badge]: https://travis-ci.org/haskell/haddock.svg?branch=ghc-8.10
+[CI page]: https://github.com/haskell/haddock/actions/workflows/ci.yml
+[CI badge]: https://github.com/haskell/haddock/actions/workflows/ci.yml/badge.svg
[Hackage page]: https://hackage.haskell.org/package/haddock
[Hackage badge]: https://img.shields.io/hackage/v/haddock.svg
-[ReST]: http://www.sphinx-doc.org/en/stable/rest.html
+[reST]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
[Documentation.Haddock]: http://hackage.haskell.org/package/haddock-api/docs/Documentation-Haddock.html
-[cabal v2]: http://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
+[cabal v2]: https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
diff --git a/doc/common-errors.rst b/doc/common-errors.rst
new file mode 100644
index 00000000..9afa4ea7
--- /dev/null
+++ b/doc/common-errors.rst
@@ -0,0 +1,19 @@
+Common Errors
+=============
+
+``parse error on input ‘-- | xxx’``
+-----------------------------------
+
+This is probably caused by the ``-- | xxx`` comment not following a declaration. I.e. use ``-- xxx`` instead. See :ref:`top-level-declaration`.
+
+``parse error on input ‘-- $ xxx’``
+----------------------------------
+
+You've probably commented out code like::
+
+ f x
+ $ xxx
+
+``-- $`` is a special syntax for named chunks, see :ref:`named-chunks`. You can fix this by escaping the ``$``::
+
+ -- \$ xxx
diff --git a/doc/index.rst b/doc/index.rst
index 0d1b8b48..f370e42f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -12,6 +12,7 @@ Contents:
intro
invoking
markup
+ common-errors
multi-components
diff --git a/doc/intro.rst b/doc/intro.rst
index fc1269f9..1f4234cb 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -25,7 +25,7 @@ in mind:
The easier it is to write documentation, the more likely the
programmer is to do it. Haddock therefore uses lightweight markup in
its annotations, taking several ideas from
- `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__. In fact,
+ `IDoc <https://web.archive.org/web/20180621053227/http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__. In fact,
Haddock can understand IDoc-annotated source code.
- The documentation should not expose any of the structure of the
@@ -59,8 +59,8 @@ in mind:
Obtaining Haddock
-----------------
-Distributions (source & binary) of Haddock can be obtained from its `web
-site <http://www.haskell.org/haddock/>`__.
+Haddock is distributed with GHC distributions, and will automatically be provided if you use
+`ghcup <https://www.haskell.org/ghcup>`__, for instance.
Up-to-date sources can also be obtained from our public GitHub
repository. The Haddock sources are at
@@ -72,77 +72,38 @@ License
The following license covers this documentation, and the Haddock source
code, except where otherwise indicated.
- Copyright 2002-2010, Simon Marlow. All rights reserved.
+ Copyright (c) 2002-2010, Simon Marlow
+ All rights reserved.
Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
+ modification, are permitted provided that the following conditions are
+ met:
- - Redistributions of source code must retain the above copyright
+ 1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
- - Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in
- the documentation and/or other materials provided with the
+ 2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the
distribution.
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS IS" AND ANY
- EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
- PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE
- LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
- CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
- SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
- BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
- LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
- NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
- SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Contributors
------------
-Haddock was originally written by Simon Marlow. Since it is an open
-source project, many people have contributed to its development over the
-years. Below is a list of contributors in alphabetical order that we
-hope is somewhat complete. If you think you are missing from this list,
-please contact us.
-
-- Ashley Yakeley
-- Benjamin Franksen
-- Brett Letner
-- Clemens Fruhwirth
-- Conal Elliott
-- David Waern
-- Duncan Coutts
-- George Pollard
-- George Russel
-- Hal Daume
-- Ian Lynagh
-- Isaac Dupree
-- Joachim Breitner
-- Krasimir Angelov
-- Lennart Augustsson
-- Luke Plant
-- Malcolm Wallace
-- Manuel Chakravarty
-- Marcin Szamotulski
-- Mark Lentczner
-- Mark Shields
-- Mateusz Kowalczyk
-- Mike Thomas
-- Neil Mitchell
-- Oliver Brown
-- Roman Cheplyaka
-- Ross Paterson
-- Sigbjorn Finne
-- Simon Hengel
-- Simon Marlow
-- Simon Peyton-Jones
-- Stefan O'Rear
-- Sven Panne
-- Thomas Schilling
-- Wolfgang Jeltsch
-- Yitzchak Gale
+A list of contributors to the project can be seen at
+``https://github.com/haskell/haddock/graphs/contributors``.
Acknowledgements
----------------
@@ -150,11 +111,11 @@ Acknowledgements
Several documentation systems provided the inspiration for Haddock, most
notably:
-- `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__
+- `IDoc <https://web.archive.org/web/20180621053227/http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__
-- `HDoc <http://www.fmi.uni-passau.de/~groessli/hdoc/>`__
+- `HDoc <https://mail.haskell.org/pipermail/haskelldoc/2001-April/000067.html>`__
-- `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`__
+- `Doxygen <https://www.doxygen.nl/index.html>`__
and probably several others I've forgotten.
diff --git a/doc/markup.rst b/doc/markup.rst
index c0b08a40..abfeb52a 100644
--- a/doc/markup.rst
+++ b/doc/markup.rst
@@ -950,24 +950,30 @@ apostrophes themselves: to hyperlink ``foo'`` one would simply type
-- | A prefix operator @'(++)'@ and an infix identifier @'`elem`'@.
-Emphasis, Bold and Monospaced Text
+Emphasis, Bold and Monospaced styled Text
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Emphasis may be added by surrounding text with ``/.../``. Other markup
-is valid inside emphasis. To have a forward slash inside of emphasis,
-just escape it: ``/fo\/o/``
+Text can be emphasized, made bold (strong) or monospaced (typewriter font)
+by surrounding it with slashes, double-underscores or at-symbols: ::
-Bold (strong) text is indicated by surrounding it with ``__...__``.
-Other markup is valid inside bold. For example, ``__/foo/__`` will make
-the emphasised text ``foo`` bold. You don't have to escape a single
-underscore if you need it bold:
-``__This_text_with_underscores_is_bold__``.
+ -- | This is /emphasized text/, __bold text__ and @monospaced text@.
-Monospaced (or typewriter) text is indicated by surrounding it with
-``@...@``. Other markup is valid inside a monospaced span: for example
-``@'f' a b@`` will hyperlink the identifier ``f`` inside the code
-fragment, but ``@__FILE__@`` will render ``FILE`` in bold with no
-underscores, which may not be what you had in mind.
+Note that those styled texts must be kept on the same line: ::
+
+ -- | Styles /do not work
+ -- | when continuing on the next line/
+
+Other markup is valid inside emphasized, bold and monospaced text.
+
+Frequent special cases:
+
+* To have a forward slash inside of emphasis, just escape it: ``/fo\/o/``.
+* There's no need to escape a single underscore if you need it
+ bold: ``__This_text_with_underscores_is_bold__``.
+* ``@'f' a b@`` will hyperlink the identifier ``f`` inside the code
+ fragment.
+* ``@__FILE__@`` will render ``FILE`` in bold with no underscores,
+ which may not be what you had in mind.
Linking to Modules
~~~~~~~~~~~~~~~~~~
@@ -1121,6 +1127,17 @@ followed by the URL enclosed in regular parentheses, for example: ::
The link text is used as a description for the URL if the output
format supports it.
+Hint: There's a `known issue <https://github.com/haskell/haddock/issues/774>`_
+that any inline link at the beginning of a line within a multi-line comment
+isn't rendered correctly: ::
+
+ {-| Some multi-line comment that has a
+ [link](https://example.com) and a
+ [reference link]: https://example.com
+ -}
+
+Adding a space or a word in front of such a link can be used as a workaround.
+
Images
~~~~~~
diff --git a/haddock-api/haddock-api.cabal b/haddock-api/haddock-api.cabal
index cd02bf25..9770061c 100644
--- a/haddock-api/haddock-api.cabal
+++ b/haddock-api/haddock-api.cabal
@@ -1,6 +1,6 @@
cabal-version: 2.0
name: haddock-api
-version: 2.24.0
+version: 2.26.0
synopsis: A documentation-generation tool for Haskell libraries
description: Haddock is a documentation-generation tool for Haskell
libraries
@@ -13,7 +13,7 @@ bug-reports: https://github.com/haskell/haddock/issues
copyright: (c) Simon Marlow, David Waern
category: Documentation
build-type: Simple
-tested-with: GHC==9.0.*
+tested-with: GHC==9.2.*
extra-source-files:
CHANGES.md
@@ -180,11 +180,11 @@ test-suite spec
Haddock.Backends.Hyperlinker.Parser
Haddock.Backends.Hyperlinker.Types
- build-depends: ghc ^>= 9.1
+ build-depends: ghc ^>= 9.3
, ghc-paths ^>= 0.1.0.12
, haddock-library ^>= 1.9.0
, xhtml ^>= 3000.2.2
- , hspec >= 2.4.4 && < 2.8
+ , hspec ^>= 2.9
, parsec ^>= 3.1.13.0
, QuickCheck >= 2.11 && ^>= 2.14
@@ -201,10 +201,11 @@ test-suite spec
, filepath
, ghc-boot
, ghc-boot-th
+ , mtl
, transformers
build-tool-depends:
- hspec-discover:hspec-discover >= 2.4.4 && < 2.8
+ hspec-discover:hspec-discover ^>= 2.9
source-repository head
type: git
diff --git a/haddock-api/src/Haddock/Backends/Hyperlinker.hs b/haddock-api/src/Haddock/Backends/Hyperlinker.hs
index 68e03fd5..89828e30 100644
--- a/haddock-api/src/Haddock/Backends/Hyperlinker.hs
+++ b/haddock-api/src/Haddock/Backends/Hyperlinker.hs
@@ -114,4 +114,3 @@ highlightScript = "highlight.js"
-- | Path to default CSS file.
defaultCssFile :: FilePath -> FilePath
defaultCssFile libdir = libdir </> "html" </> "solarized.css"
-
diff --git a/haddock-api/src/Haddock/Convert.hs b/haddock-api/src/Haddock/Convert.hs
index fd5300d2..ceefedf3 100644
--- a/haddock-api/src/Haddock/Convert.hs
+++ b/haddock-api/src/Haddock/Convert.hs
@@ -411,6 +411,7 @@ synifyDataCon use_gadt_syntax dc =
return $ noLocA $ ConDeclGADT
{ con_g_ext = noAnn
, con_names = [name]
+ , con_dcolon = noHsUniTok
, con_bndrs = noLocA outer_bndrs
, con_mb_cxt = ctx
, con_g_args = hat
diff --git a/haddock-api/src/Haddock/Interface/Rename.hs b/haddock-api/src/Haddock/Interface/Rename.hs
index 6057bf75..cbc7e58f 100644
--- a/haddock-api/src/Haddock/Interface/Rename.hs
+++ b/haddock-api/src/Haddock/Interface/Rename.hs
@@ -519,6 +519,7 @@ renameCon decl@(ConDeclH98 { con_name = lname, con_ex_tvs = ltyvars
, con_args = details', con_doc = mbldoc' })
renameCon ConDeclGADT { con_names = lnames, con_bndrs = bndrs
+ , con_dcolon = dcol
, con_mb_cxt = lcontext, con_g_args = details
, con_res_ty = res_ty
, con_doc = mbldoc } = do
@@ -529,7 +530,8 @@ renameCon ConDeclGADT { con_names = lnames, con_bndrs = bndrs
res_ty' <- renameLType res_ty
mbldoc' <- mapM renameLDocHsSyn mbldoc
return (ConDeclGADT
- { con_g_ext = noExtField, con_names = lnames', con_bndrs = bndrs'
+ { con_g_ext = noExtField, con_names = lnames'
+ , con_dcolon = dcol, con_bndrs = bndrs'
, con_mb_cxt = lcontext', con_g_args = details'
, con_res_ty = res_ty', con_doc = mbldoc' })
diff --git a/haddock-library/haddock-library.cabal b/haddock-library/haddock-library.cabal
index 72c11f75..f6d88c81 100644
--- a/haddock-library/haddock-library.cabal
+++ b/haddock-library/haddock-library.cabal
@@ -28,6 +28,7 @@ tested-with: GHC == 7.4.2
, GHC == 8.8.3
, GHC == 8.10.1
, GHC == 9.0.1
+ , GHC == 9.2.0
extra-source-files:
CHANGES.md
@@ -39,10 +40,8 @@ common lib-defaults
build-depends:
, base >= 4.5 && < 4.17
- , bytestring ^>= 0.9.2.1 || ^>= 0.10.0.0 || ^>= 0.11.0.0
, containers ^>= 0.4.2.1 || ^>= 0.5.0.0 || ^>= 0.6.0.1
- , transformers ^>= 0.3.0.0 || ^>= 0.4.1.0 || ^>= 0.5.0.0
- , text ^>= 1.2.3.0
+ , text ^>= 1.2.3.0 || ^>= 2.0
, parsec ^>= 3.1.13.0
ghc-options: -funbox-strict-fields -Wall
@@ -87,7 +86,7 @@ test-suite spec
Documentation.Haddock.Parser.Identifier
build-depends:
- , QuickCheck ^>= 2.11 || ^>= 2.13.2 || ^>= 2.14
+ , QuickCheck ^>= 2.11 || ^>= 2.13.2 || ^>= 2.14
, deepseq ^>= 1.3.0.0 || ^>= 1.4.0.0
-- NB: build-depends & build-tool-depends have independent
@@ -95,10 +94,10 @@ test-suite spec
-- version of `hspec` & `hspec-discover` to ensure
-- intercompatibility
build-depends:
- , hspec >= 2.4.4 && < 2.8
+ , hspec >= 2.4.4 && < 2.10
build-tool-depends:
- , hspec-discover:hspec-discover >= 2.4.4 && < 2.8
+ , hspec-discover:hspec-discover >= 2.4.4 && < 2.10
test-suite fixtures
type: exitcode-stdio-1.0
@@ -116,7 +115,7 @@ test-suite fixtures
, directory ^>= 1.3.0.2
, filepath ^>= 1.4.1.2
, optparse-applicative ^>= 0.15
- , tree-diff ^>= 0.1
+ , tree-diff ^>= 0.2
source-repository head
type: git
diff --git a/haddock-test/src/Test/Haddock/Config.hs b/haddock-test/src/Test/Haddock/Config.hs
index e4829588..2905dc8f 100644
--- a/haddock-test/src/Test/Haddock/Config.hs
+++ b/haddock-test/src/Test/Haddock/Config.hs
@@ -18,7 +18,7 @@ import Data.Maybe
import Distribution.Text
import Distribution.Types.PackageName
import Distribution.InstalledPackageInfo
-import Distribution.Simple.Compiler
+import Distribution.Simple.Compiler (PackageDB(..))
import Distribution.Simple.GHC
import Distribution.Simple.PackageIndex
import Distribution.Simple.Program
diff --git a/haddock.cabal b/haddock.cabal
index 5c09f80d..37cd5a42 100644
--- a/haddock.cabal
+++ b/haddock.cabal
@@ -33,7 +33,7 @@ bug-reports: https://github.com/haskell/haddock/issues
copyright: (c) Simon Marlow, David Waern
category: Documentation
build-type: Simple
-tested-with: GHC==9.0.*
+tested-with: GHC==9.4.*
extra-source-files:
CHANGES.md
diff --git a/html-test/ref/Instances.html b/html-test/ref/Instances.html
index e99f82e4..109e866c 100644
--- a/html-test/ref/Instances.html
+++ b/html-test/ref/Instances.html
@@ -262,7 +262,9 @@
></span
> <a href="#" title="Instances"
>Foo</a
- > []</span
+ > <a href="#" title="GHC.List"
+ >List</a
+ ></span
> <a href="#" class="selflink"
>#</a
></td
@@ -900,7 +902,9 @@
></span
> <a href="#" title="Instances"
>Bar</a
- > [] (a, a)</span
+ > <a href="#" title="GHC.List"
+ >List</a
+ > (a, a)</span
> <a href="#" class="selflink"
>#</a
></td
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-23 05:04:55 +0000