[Git][ghc/ghc][master] Various documentation fixes

Sat Sep 26 01:16:00 UTC 2020


 Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC


Commits:
83407ffc by Krzysztof Gogolewski at 2020-09-25T21:15:53-04:00
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

- - - - -


9 changed files:

- docs/users_guide/conf.py
- docs/users_guide/expected-undocumented-flags.txt
- docs/users_guide/extending_ghc.rst
- docs/users_guide/exts/defer_type_errors.rst
- docs/users_guide/exts/ffi.rst
- docs/users_guide/exts/safe_haskell.rst
- docs/users_guide/exts/template_haskell.rst
- docs/users_guide/exts/typed_holes.rst
- docs/users_guide/using-optimisation.rst


Changes:

=====================================
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}


=====================================
docs/users_guide/expected-undocumented-flags.txt
=====================================
@@ -18,7 +18,6 @@
 -XAutoDeriveTypeable
 -XDoAndIfThenElse
 -XDoRec
--XGHCForeignImportPrim
 -XGenerics
 -XImplicitPrelude
 -XJavaScriptFFI


=====================================
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


=====================================
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>`_).
 
 


=====================================
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# #)
 


=====================================
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
 


=====================================
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`)
 


=====================================
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
 


=====================================
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`.



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/83407ffc7acc00cc025b9f6ed063add9ab9f9bcc

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/83407ffc7acc00cc025b9f6ed063add9ab9f9bcc
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20200925/50a11976/attachment-0001.html>
