From 83407ffc7acc00cc025b9f6ed063add9ab9f9bcc Mon Sep 17 00:00:00 2001
From: Krzysztof Gogolewski <krzysztof.gogolewski@tweag.io>
Date: Fri, 25 Sep 2020 02:52:19 +0200
Subject: [PATCH] Various documentation fixes
* Remove UnliftedFFITypes from conf. Some time ago, this extension
was undocumented and we had to silence a warning.
This is no longer needed.
* Use r'' in conf.py. This fixes a Sphinx warning:
WARNING: Support for evaluating Python 2 syntax is deprecated and will be removed in Sphinx 4.0. Convert docs/users_guide/conf.py to Python 3 syntax.
* Mark GHCForeignImportPrim as documented
* Fix formatting in template_haskell.rst
* Remove 'recursive do' from the list of unsupported items in TH
---
docs/users_guide/conf.py | 7 ++-----
docs/users_guide/expected-undocumented-flags.txt | 1 -
docs/users_guide/extending_ghc.rst | 4 ++--
docs/users_guide/exts/defer_type_errors.rst | 3 ++-
docs/users_guide/exts/ffi.rst | 9 +++++++--
docs/users_guide/exts/safe_haskell.rst | 4 ++--
docs/users_guide/exts/template_haskell.rst | 9 +++------
docs/users_guide/exts/typed_holes.rst | 2 ++
docs/users_guide/using-optimisation.rst | 2 +-
9 files changed, 21 insertions(+), 20 deletions(-)
diff --git a/docs/users_guide/conf.py b/docs/users_guide/conf.py
index 5c372cd5fa9f..ffe4d8757a4e 100644
--- a/docs/users_guide/conf.py
+++ b/docs/users_guide/conf.py
@@ -38,9 +38,6 @@ nitpick_ignore = [
("extension", "DoAndIfThenElse"),
("extension", "RelaxedPolyRec"),
-
- # See #16629
- ("extension", "UnliftedFFITypes"),
]
rst_prolog = """
@@ -96,13 +93,13 @@ htmlhelp_basename = 'GHCUsersGuide'
latex_elements = {
'inputenc': '',
'utf8extra': '',
- 'preamble': '''
+ 'preamble': r'''
\usepackage{fontspec}
\usepackage{makeidx}
\setsansfont{DejaVu Sans}
\setromanfont{DejaVu Serif}
\setmonofont{DejaVu Sans Mono}
-\setlength{\\tymin}{45pt}
+\setlength{\tymin}{45pt}
% Avoid a torrent of over-full \hbox warnings
\usepackage{microtype}
diff --git a/docs/users_guide/expected-undocumented-flags.txt b/docs/users_guide/expected-undocumented-flags.txt
index 1b5b8056166b..68dcd2d1df84 100644
--- a/docs/users_guide/expected-undocumented-flags.txt
+++ b/docs/users_guide/expected-undocumented-flags.txt
@@ -18,7 +18,6 @@
-XAutoDeriveTypeable
-XDoAndIfThenElse
-XDoRec
--XGHCForeignImportPrim
-XGenerics
-XImplicitPrelude
-XJavaScriptFFI
diff --git a/docs/users_guide/extending_ghc.rst b/docs/users_guide/extending_ghc.rst
index a5ba52e88e71..483334d17c18 100644
--- a/docs/users_guide/extending_ghc.rst
+++ b/docs/users_guide/extending_ghc.rst
@@ -800,8 +800,8 @@ displayed.
import GHC.Hs.Decls
import GHC.Hs.Expr
import GHC.Hs.ImpExp
- import Avail
- import Outputable
+ import GHC.Types.Avail
+ import GHC.Utils.Outputable
import GHC.Hs.Doc
plugin :: Plugin
diff --git a/docs/users_guide/exts/defer_type_errors.rst b/docs/users_guide/exts/defer_type_errors.rst
index 2b3f13976fcc..146fc0176011 100644
--- a/docs/users_guide/exts/defer_type_errors.rst
+++ b/docs/users_guide/exts/defer_type_errors.rst
@@ -115,6 +115,7 @@ In a few cases, even equality constraints cannot be deferred. Specifically:
This type signature contains a kind error which cannot be deferred.
-- Type equalities under a forall cannot be deferred (c.f. #14605).
+- Type equalities under a forall cannot be deferred (c.f. `#14605
+ <https://gitlab.haskell.org/ghc/ghc/issues/14605>`_).
diff --git a/docs/users_guide/exts/ffi.rst b/docs/users_guide/exts/ffi.rst
index 76e8bdb97ef6..1d40017293b1 100644
--- a/docs/users_guide/exts/ffi.rst
+++ b/docs/users_guide/exts/ffi.rst
@@ -263,8 +263,13 @@ and is not permitted to appear nested within the type, as in the following
Primitive imports
~~~~~~~~~~~~~~~~~
-GHC extends the FFI with an additional calling convention ``prim``,
-e.g.: ::
+.. extension:: GHCForeignImportPrim
+ :shortdesc: Enable prim calling convention. Intended for internal use only.
+
+ :since: 6.12.1
+
+With :extension:`GHCForeignImportPrim`, GHC extends the FFI with an additional
+calling convention ``prim``, e.g.: ::
foreign import prim "foo" foo :: ByteArray# -> (# Int#, Int# #)
diff --git a/docs/users_guide/exts/safe_haskell.rst b/docs/users_guide/exts/safe_haskell.rst
index edfedda4b25b..7cbfdc0ef95b 100644
--- a/docs/users_guide/exts/safe_haskell.rst
+++ b/docs/users_guide/exts/safe_haskell.rst
@@ -781,7 +781,7 @@ And five warning flags:
:shortdesc: warn when an explicitly Safe Haskell module imports a Safe-Inferred one
:type: dynamic
:reverse: -Wno-inferred-safe-imports
- :category:
+ :category: warnings
:since: 8.10.1
@@ -815,7 +815,7 @@ And five warning flags:
:shortdesc: warn when the Safe Haskell mode is not explicitly specified.
:type: dynamic
:reverse: -Wno-missing-safe-haskell-mode
- :category:
+ :category: warnings
:since: 8.10.1
diff --git a/docs/users_guide/exts/template_haskell.rst b/docs/users_guide/exts/template_haskell.rst
index a33949a1f119..075608d77cbd 100644
--- a/docs/users_guide/exts/template_haskell.rst
+++ b/docs/users_guide/exts/template_haskell.rst
@@ -109,7 +109,7 @@ The :extension:`TemplateHaskellQuotes` extension is considered safe under
plusC = [| $oneC + $twoC |]
-- The precise type of a quotation depends on the types of the nested splices inside it::
+- The precise type of a quotation depends on the types of the nested splices inside it::
-- Add a redundant constraint to demonstrate that constraints on the
-- monad used to build the representation are propagated when using nested
@@ -125,9 +125,8 @@ The :extension:`TemplateHaskellQuotes` extension is considered safe under
Remember, a top-level splice still requires its argument to be of type ``Q Exp``.
So then splicing in ``g`` will cause ``m`` to be instantiated to ``Q``::
- h :: Int
- h = $(g) -- m ~ Q
-
+ h :: Int
+ h = $(g) -- m ~ Q
- A *typed* expression splice is written ``$$x``, where ``x`` is
is an arbitrary expression.
@@ -376,8 +375,6 @@ The :extension:`TemplateHaskellQuotes` extension is considered safe under
However, there are some GHC-specific extensions which expression
quotations currently do not support, including
- - Recursive ``do``-statements (see :ghc-ticket:`1262`)
-
- Type holes in typed splices (see :ghc-ticket:`10945` and
:ghc-ticket:`10946`)
diff --git a/docs/users_guide/exts/typed_holes.rst b/docs/users_guide/exts/typed_holes.rst
index 5d2a58db936b..170824ee4f6d 100644
--- a/docs/users_guide/exts/typed_holes.rst
+++ b/docs/users_guide/exts/typed_holes.rst
@@ -546,6 +546,7 @@ Sorting can be toggled with :ghc-flag:`-fsort-valid-hole-fits`
:shortdesc: Sort valid hole fits by size.
:type: dynamic
:reverse: -fno-sort-by-size-hole-fits
+ :category: verbosity
:default: on
@@ -557,6 +558,7 @@ Sorting can be toggled with :ghc-flag:`-fsort-valid-hole-fits`
:shortdesc: Sort valid hole fits by subsumption.
:type: dynamic
:reverse: -fno-sort-by-subsumption-hole-fits
+ :category: verbosity
:default: off
diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst
index 4c44509f211a..c278e6903d3a 100644
--- a/docs/users_guide/using-optimisation.rst
+++ b/docs/users_guide/using-optimisation.rst
@@ -361,7 +361,7 @@ by saying ``-fno-wombat``.
:default: on
Use a special demand transformer for dictionary selectors.
- Behaviour is unconditionally enabled starting with 8.14
+ Behaviour is unconditionally enabled starting with 9.2
.. ghc-flag:: -fdo-eta-reduction
:shortdesc: Enable eta-reduction. Implied by :ghc-flag:`-O`.
--
GitLab