Merge remote-tracking branch 'origin/ghc-9.0' into ghc-head

1 files changed, 73 insertions, 46 deletions

diff --git a/doc/markup.rst b/doc/markup.rst
index 8f926961..8935b765 100644
--- a/doc/markup.rst
+++ b/doc/markup.rst
@@ -131,7 +131,7 @@ or like this: ::
           b  -- ^ This is the documentation for the argument of type 'b'
 
 There is one edge case that is handled differently: only one ``-- ^``
-annotation occuring after the constructor and all its arguments is
+annotation occurring after the constructor and all its arguments is
 applied to the constructor, not its last argument: ::
 
     data T a b
@@ -156,8 +156,8 @@ Alternative layout styles are generally accepted by Haddock - for
 example doc comments can appear before or after the comma in separated
 lists such as the list of record fields above.
 
-In case that more than one constructor exports a field with the same
-name, the documentation attached to the first occurence of the field
+In cases where more than one constructor exports a field with the same
+name, the documentation attached to the first occurrence of the field
 will be used, even if a comment is not present. ::
 
     data T a = A { someField :: a -- ^ Doc for someField of A
@@ -165,7 +165,7 @@ will be used, even if a comment is not present. ::
              | B { someField :: a -- ^ Doc for someField of B
                  }
 
-In the above example, all occurences of ``someField`` in the
+In the above example, all occurrences of ``someField`` in the
 documentation are going to be documented with
 ``Doc for someField of A``. Note that Haddock versions 2.14.0 and before
 would join up documentation of each field and render the result. The
@@ -223,7 +223,7 @@ module documentation example and then talk about the fields. ::
     {-|
     Module      : W
     Description : Short description
-    Copyright   : (c) Some Guy, 2013
+    Copyright   : (c) Some Person, 2013
                       Someone Else, 2014
     License     : GPL-3
     Maintainer  : sample@email.com
@@ -238,37 +238,37 @@ module documentation example and then talk about the fields. ::
 
 All fields are optional but they must be in order if they do appear.
 Multi-line fields are accepted but the consecutive lines have to start
-indented more than their label. If your label is indented one space as
+indented more than their label. If your label is indented one space, as
 is often the case with the ``--`` syntax, the consecutive lines have
 to start at two spaces at the very least. For example, above we saw a
 multiline ``Copyright`` field: ::
 
     {-|
     ...
-    Copyright   : (c) Some Guy, 2013
+    Copyright   : (c) Some Person, 2013
                       Someone Else, 2014
     ...
     -}
 
-That could equivalently be written as ::
+That could equivalently be written as: ::
 
     -- | ...
     -- Copyright:
-    --  (c) Some Guy, 2013
+    --  (c) Some Person, 2013
     --  Someone Else, 2014
     -- ...
 
-or as ::
+or as: ::
 
     -- | ...
-    -- Copyright: (c) Some Guy, 2013
+    -- Copyright: (c) Some Person, 2013
     --     Someone Else, 2014
     -- ...
 
-but not as ::
+but not as: ::
 
     -- | ...
-    -- Copyright: (c) Some Guy, 2013
+    -- Copyright: (c) Some Person, 2013
     -- Someone Else, 2014
     -- ...
 
@@ -352,7 +352,7 @@ Documentation Structure Examples
 
 We now give several examples that produce similar results and
 illustrate most of the structural markup features. The first two
-example use an export list, but the third example does not.
+examples use an export list, but the third example does not.
 
 The first example, using an export list with :ref:`section-headings`
 and inline section descriptions: ::
@@ -362,7 +362,7 @@ and inline section descriptions: ::
         --
         -- | There is a "smart" importer, 'readImage', that determines
         -- the image format from the file extension, and several
-        -- "dumb" format-specific importers that decode the file at
+        -- "dumb" format-specific importers that decode the file as
         -- the specified type.
         readImage
       , readPngImage
@@ -417,7 +417,7 @@ defined elsewhere (the ``$imageImporters``; see :ref:`named-chunks`):
     --
     -- There is a "smart" importer, 'readImage', that determines the
     -- image format from the file extension, and several "dumb"
-    -- format-specific importers that decode the file at the specified
+    -- format-specific importers that decode the file as the specified
     -- type.
 
     -- | Read an image, guessing the format from the file name.
@@ -450,7 +450,7 @@ The third example, without an export list: ::
     --
     -- There is a "smart" importer, 'readImage', that determines the
     -- image format from the file extension, and several "dumb"
-    -- format-specific importers that decode the file at the specified
+    -- format-specific importers that decode the file as the specified
     -- type.
 
     -- | Read an image, guessing the format from the file name.
@@ -508,12 +508,25 @@ on, where the number of ``*``\ s indicates the level of the heading
 If you use section headings, then Haddock will generate a table of
 contents at the top of the module documentation for you.
 
+By default, when generating HTML documentation Haddock will create an
+anchor to each section of the form ``#g:n``, where ``n`` is an integer
+that might change as you add new section headings. If you want to
+create stable links, you can add an explicit anchor (see
+:ref:`anchors`) after the section heading: ::
+
+  module Foo (
+    -- * Classes #classes#
+    C(..)
+  ) where
+
+This will create an HTML anchor ``#g:classes`` to the section.
+
 The alternative style of placing the commas at the beginning of each
-line is also supported. e.g.: ::
+line is also supported, e.g.: ::
 
     module Foo (
       -- * Classes
-      , C(..)
+        C(..)
       -- * Types
       -- ** A data type
       , T
@@ -526,7 +539,7 @@ line is also supported. e.g.: ::
 
 When not using an export list, you may insert section headers in the
 module body. Such section headers associate with all entities
-declaried up until the next section header. For example: ::
+declared up until the next section header. For example: ::
 
     module Foo where
 
@@ -601,7 +614,7 @@ re-exporting module.
 It is often desirable to include a chunk of documentation which is not
 attached to any particular Haskell declaration, for example, when
 giving summary documentation for a group of related definitions (see
-:ref:`structure-examples`). In addition to including such documenation
+:ref:`structure-examples`). In addition to including such documentation
 chunks at the top of the file, as part of the
 :ref:`module-description`, you can also associate them with
 :ref:`section-headings`.
@@ -655,14 +668,14 @@ headings, depending on whether you are using an export list or not:
        -- Here is a large chunk of documentation which may be referred to by
        -- the name $doc.
 
-   Just like with entity declariations when not using an export list,
+   Just like with entity declarations when not using an export list,
    named chunks of documentation are associated with the preceding
    section header here, or with the implicit top-level documentation
    section if there is no preceding section header.
 
    **Warning**: the form used in the first bullet above, where the
    chunk is not named, *does not work* when you aren't using an
-   export list. For example ::
+   export list. For example: ::
 
        module Foo where
 
@@ -673,7 +686,7 @@ headings, depending on whether you are using an export list or not:
        -- | The fooifier.
        foo :: ...
 
-   will result in ``Some documentation not ...`` being attached to
+   will result in ``Some documentation not ...`` being attached to the
    *next* entity declaration, here ``foo``, in addition to any other
    documentation that next entity already has!
 
@@ -743,7 +756,7 @@ type in ``C`` will therefore point locally to ``C.T``.
 Module Attributes
 -----------------
 
-Certain attributes may be specified for each module which affects the
+Certain attributes may be specified for each module which affect the
 way that Haddock generates documentation for that module. Attributes are
 specified in a comma-separated list in an
 ``{-# OPTIONS_HADDOCK ... #-}`` pragma at the top of the module, either
@@ -794,7 +807,7 @@ Markup
 
 Haddock understands certain textual cues inside documentation
 annotations that tell it how to render the documentation. The cues (or
-“markup”) have been designed to be simple and mnemonic in ASCII so that
+“markup”) have been designed to be simple and mnemonic in ASCII so
 the programmer doesn't have to deal with heavyweight annotations when
 editing documentation comments.
 
@@ -807,8 +820,8 @@ comment.
 Special Characters
 ~~~~~~~~~~~~~~~~~~
 
-The following characters have special meanings in documentation
-comments: ``\``, ``/``, ``'``, `````, ``"``, ``@``, ``<``, ``$``, ``#``. To insert a
+The following characters have special meanings in documentation comments:
+``\``, ``/``, ``'``, `````, ``"``, ``@``, ``<``, ``$``, ``#``. To insert a
 literal occurrence of one of these special characters, precede it with a
 backslash (``\``).
 
@@ -826,7 +839,7 @@ Character References
 
 Although Haskell source files may contain any character from the Unicode
 character set, the encoding of these characters as bytes varies between
-systems, so that only source files restricted to the ASCII character set
+systems. Consequently, only source files restricted to the ASCII character set
 are portable. Other characters may be specified in character and string
 literals using Haskell character escapes. To represent such characters
 in documentation comments, Haddock supports SGML-style numeric character
@@ -913,6 +926,17 @@ If ``M.T`` is not otherwise in scope, then Haddock will simply emit a
 link pointing to the entity ``T`` exported from module ``M`` (without
 checking to see whether either ``M`` or ``M.T`` exist).
 
+Since values and types live in different namespaces in Haskell, it is possible
+for a reference such as ``'X'`` to be ambiguous. In such a case, Haddock
+defaults to pointing to the type. The ambiguity can be overcome by explicitly
+specifying a namespace, by way of a ``v`` (for value) or ``t`` (for type)
+immediately before the link: ::
+
+    -- | An implicit reference to  'X', the type constructor
+    --   An explicit reference to v'X', the data constructor
+    --   An explicit reference to t'X', the type constructor
+    data X = X
+
 To make life easier for documentation writers, a quoted identifier is
 only interpreted as such if the quotes surround a lexically valid
 Haskell identifier. This means, for example, that it normally isn't
@@ -922,14 +946,9 @@ necessary to escape the single quote when used as an apostrophe: ::
 
 Nothing special is needed to hyperlink identifiers which contain
 apostrophes themselves: to hyperlink ``foo'`` one would simply type
-``'foo''``. Hyperlinking operators works in exactly the same way.
-
-Note that it is not possible to directly hyperlink an identifier in infix
-form or an operator in prefix form. The next best thing to do is to wrap
-the whole identifier in monospaced text and put the parentheses/backticks
-outside of the identifier, but inside the link: ::
+``'foo''``. Hyperlinking operators works in exactly the same way. ::
 
-    -- | A prefix operator @('++')@ and an infix identifier @\``elem`\`@.
+    -- | A prefix operator @'(++)'@ and an infix identifier @'`elem`'@.
 
 Emphasis, Bold and Monospaced Text
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -947,7 +966,7 @@ underscore if you need it bold:
 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 
+fragment, but ``@__FILE__@`` will render ``FILE`` in bold with no
 underscores, which may not be what you had in mind.
 
 Linking to Modules
@@ -968,7 +987,7 @@ Itemized and Enumerated Lists
 
 A bulleted item is represented by preceding a paragraph with either
 “``*``” or “``-``”. A sequence of bulleted paragraphs is rendered as an
-itemized list in the generated documentation, eg.: ::
+itemized list in the generated documentation, e.g.: ::
 
     -- | This is a bulleted list:
     --
@@ -1007,7 +1026,7 @@ You can have more than one line of content in a list element: ::
 
 You can even nest whole paragraphs inside of list elements. The rules
 are 4 spaces for each indentation level. You're required to use a
-newline before such nested paragraph: ::
+newline before such nested paragraphs: ::
 
     {-|
     * Beginning of list
@@ -1094,7 +1113,7 @@ followed by the URL enclosed in regular parentheses, for example: ::
 
     [some link](http://example.com)
 
-The link text is used as a descriptive text for the URL, if the output
+The link text is used as a description for the URL if the output
 format supports it.
 
 Images
@@ -1107,8 +1126,8 @@ like this: ::
     ![image description](pathtoimage.png)
 
 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.
+documentation. The image description is used as replacement text and/or
+an image title.
 
 Mathematics / LaTeX
 ~~~~~~~~~~~~~~~~~~~
@@ -1128,10 +1147,16 @@ the mathematics via `MathJax <https://www.mathjax.org>`__.
 Grid Tables
 ~~~~~~~~~~~
 
-Inspired by reSTs grid tables Haddock supports a complete table representation via a grid-like "ASCII art". Grid tables are described with a visual grid made up of the characters "-", "=", "|", and "+". The hyphen ("-") is used for horizontal lines (row separators). The equals sign ("=") may be used to separate optional header rows from the table body. The vertical bar ("|") is used for vertical lines (column separators). The plus sign ("+") is used for intersections of horizontal and vertical lines. ::
+Inspired by reSTs grid tables, Haddock supports a complete table representation
+via grid-like "ASCII art". Grid tables are described with a visual grid made
+up of the characters "-", "=", "|", and "+". The hyphen ("-") is used for
+horizontal lines (row separators). The equals sign ("=") may be used to
+separate optional header rows from the table body. The vertical bar ("|") is
+used for vertical lines (column separators). The plus sign ("+") is used for
+intersections of horizontal and vertical lines. ::
 
-    -- | This is a grid table: 
-    -- 
+    -- | This is a grid table:
+    --
     -- +------------------------+------------+----------+----------+
     -- | Header row, column 1   | Header 2   | Header 3 | Header 4 |
     -- | (header rows optional) |            |          |          |
@@ -1145,6 +1170,8 @@ Inspired by reSTs grid tables Haddock supports a complete table representation v
     -- | body row 4             |            | \]                  |
     -- +------------------------+------------+---------------------+
 
+.. _anchors:
+
 Anchors
 ~~~~~~~
 
@@ -1220,7 +1247,7 @@ Since
 ^^^^^
 
 ``@since`` annotation can be used to convey information about when the
-function was introduced or when it has changed in the way significant to
+function was introduced or when it has changed in a way significant to
 the user. ``@since`` is a paragraph-level element. While multiple such
 annotations are not an error, only the one to appear in the comment last
 will be used. ``@since`` has to be followed with a version number, no