From 14c4f7014d1bbdf51a79745821fcfc39e7db0ec9 Mon Sep 17 00:00:00 2001 From: Krzysztof Gogolewski Date: Fri, 29 Jan 2021 20:05:14 +0100 Subject: Documentation fixes - Add missing :since: for NondecreasingIndentation and OverlappingInstances - Remove duplicated descriptions for Safe Haskell flags and UndecidableInstances. Instead, the sections contain a link. - compare-flags: Also check for options supported by ghci. This uncovered two more that are not documented. The flag -smp was removed. - Formatting fixes - Remove the warning about -XNoImplicitPrelude - it was written in 1996, the extension is no longer dangerous. - Fix misspelled :reverse: flags Fixes #18958. --- docs/users_guide/bugs.rst | 16 +++++++++------- docs/users_guide/compare-flags.py | 13 +++++++++---- docs/users_guide/debug-info.rst | 2 +- docs/users_guide/expected-undocumented-flags.txt | 3 ++- docs/users_guide/exts/instances.rst | 2 ++ docs/users_guide/exts/safe_imports.rst | 24 ------------------------ docs/users_guide/exts/template_haskell.rst | 2 +- docs/users_guide/exts/type_families.rst | 12 ++++-------- docs/users_guide/exts/typed_holes.rst | 2 +- docs/users_guide/ghci.rst | 1 + docs/users_guide/gone_wrong.rst | 4 +--- docs/users_guide/phases.rst | 2 +- docs/users_guide/profiling.rst | 2 +- docs/users_guide/using-optimisation.rst | 9 ++++----- docs/users_guide/using-warnings.rst | 6 +++--- 15 files changed, 40 insertions(+), 60 deletions(-) (limited to 'docs') diff --git a/docs/users_guide/bugs.rst b/docs/users_guide/bugs.rst index cfcfc0417c..2f6eecd54a 100644 --- a/docs/users_guide/bugs.rst +++ b/docs/users_guide/bugs.rst @@ -121,6 +121,8 @@ Context-free syntax :shortdesc: Allow nested contexts to be at the same indentation level as its enclosing context. + :since: 7.2.1 + Allow nested contexts to be at the same indentation level as its enclosing context. @@ -189,7 +191,7 @@ For example Will warn you with -:: +.. code-block:: none • Could not deduce (MonadFail m) arising from a do statement @@ -199,7 +201,7 @@ Will warn you with mayFail :: forall (m :: * -> *). MonadIO m => m () And indeed, since the `Monad `__ class does not have the ``fail`` method anymore, -we need to explicitly add ``(MonadFail m)`` to the contraints of the function. +we need to explicitly add ``(MonadFail m)`` to the constraints of the function. .. _infelicities-decls: @@ -337,10 +339,10 @@ Numbers, basic types, and built-in classes by: - Whenever you make a ``Num`` instance of a type, also make - ``Show`` and ``Eq`` instances, and + ``Show`` and ``Eq`` instances, and - Whenever you give a function, instance or class a ``Num t`` - constraint, also give it ``Show t`` and ``Eq t`` constraints. + constraint, also give it ``Show t`` and ``Eq t`` constraints. ``Bits`` superclass The ``Bits`` class does not have a ``Num`` superclass. It @@ -350,13 +352,13 @@ Numbers, basic types, and built-in classes You can make code that works with both Haskell 2010 and GHC by: - Whenever you make a ``Bits`` instance of a type, also make a - ``Num`` instance, and + ``Num`` instance, and - Whenever you give a function, instance or class a ``Bits t`` - constraint, also give it a ``Num t`` constraint, and + constraint, also give it a ``Num t`` constraint, and - Always define the ``bit``, ``testBit`` and ``popCount`` methods - in ``Bits`` instances. + in ``Bits`` instances. ``Read`` class methods The ``Read`` class has two extra methods, ``readPrec`` and diff --git a/docs/users_guide/compare-flags.py b/docs/users_guide/compare-flags.py index 81a11b90e5..e858e3011b 100755 --- a/docs/users_guide/compare-flags.py +++ b/docs/users_guide/compare-flags.py @@ -49,8 +49,11 @@ def read_documented_flags(doc_flags) -> Set[str]: def read_ghc_flags(ghc_path: str) -> Set[str]: ghc_output = subprocess.check_output([ghc_path, '--show-options']) - flags = {flag.strip() for flag in ghc_output.decode('UTF-8').split('\n')} - return {flag for flag in flags + ghci_output = subprocess.check_output([ghc_path, '--interactive', '--show-options']) + + return {flag + for flag in ghc_output.decode('UTF-8').splitlines() + + ghci_output.decode('UTF-8').splitlines() if not expected_undocumented(flag) if flag != ''} @@ -61,9 +64,11 @@ def main() -> None: import argparse parser = argparse.ArgumentParser() parser.add_argument('--ghc', type=argparse.FileType('r'), - help='path of GHC executable') + help='path of GHC executable', + required=True) parser.add_argument('--doc-flags', type=argparse.FileType(mode='r', encoding='UTF-8'), - help='path of ghc-flags.txt output from Sphinx') + help='path of ghc-flags.txt output from Sphinx', + required=True) args = parser.parse_args() doc_flags = read_documented_flags(args.doc_flags) diff --git a/docs/users_guide/debug-info.rst b/docs/users_guide/debug-info.rst index 42afa9078f..e18f0287a4 100644 --- a/docs/users_guide/debug-info.rst +++ b/docs/users_guide/debug-info.rst @@ -268,7 +268,7 @@ In particular GHC produces the following DWARF sections, ``.debug_arange`` Address range information necessary for efficient lookup in debug information. -.. _dwarf_dies: +.. _dwarf-dies: Debugging information entities ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/users_guide/expected-undocumented-flags.txt b/docs/users_guide/expected-undocumented-flags.txt index fdcf1eaee2..aba8f87a8c 100644 --- a/docs/users_guide/expected-undocumented-flags.txt +++ b/docs/users_guide/expected-undocumented-flags.txt @@ -63,6 +63,7 @@ -fghci-history -fghci-sandbox -fhistory-size +-fimplicit-import-qualified -fimplicit-params -fimplicit-prelude -firrefutable-tuples @@ -72,6 +73,7 @@ -fmonomorphism-restriction -fnum-constant-folding -fpre-inlining +-fprint-bind-contents -freduction-depth -frewrite-rules -fscoped-type-variables @@ -110,7 +112,6 @@ -rtsopts=ignoreAll -rtsopts=none -rtsopts=some --smp -syslib -this-component-id -ticky-LNE diff --git a/docs/users_guide/exts/instances.rst b/docs/users_guide/exts/instances.rst index 01655bb05b..b8041cdb8d 100644 --- a/docs/users_guide/exts/instances.rst +++ b/docs/users_guide/exts/instances.rst @@ -324,6 +324,8 @@ Overlapping instances .. extension:: OverlappingInstances :shortdesc: Enable overlapping instances. + :since: 6.8.1 + Deprecated extension to weaken checks intended to ensure instance resolution termination. diff --git a/docs/users_guide/exts/safe_imports.rst b/docs/users_guide/exts/safe_imports.rst index 51a17f3bf8..be6016d032 100644 --- a/docs/users_guide/exts/safe_imports.rst +++ b/docs/users_guide/exts/safe_imports.rst @@ -3,30 +3,6 @@ Safe imports ~~~~~~~~~~~~ -.. extension:: Safe - :shortdesc: Enable the :ref:`Safe Haskell ` Safe mode. - :noindex: - - :since: 7.2.1 - - Declare the Safe Haskell state of the current module. - -.. extension:: Trustworthy - :shortdesc: Enable the :ref:`Safe Haskell ` Trustworthy mode. - :noindex: - - :since: 7.2.1 - - Declare the Safe Haskell state of the current module. - -.. extension:: Unsafe - :shortdesc: Enable Safe Haskell Unsafe mode. - :noindex: - - :since: 7.4.1 - - Declare the Safe Haskell state of the current module. - With the :extension:`Safe`, :extension:`Trustworthy` and :extension:`Unsafe` language flags, GHC extends the import declaration syntax to take an optional ``safe`` keyword after the ``import`` keyword. This feature is part of the Safe diff --git a/docs/users_guide/exts/template_haskell.rst b/docs/users_guide/exts/template_haskell.rst index 075608d77c..8e617f3852 100644 --- a/docs/users_guide/exts/template_haskell.rst +++ b/docs/users_guide/exts/template_haskell.rst @@ -386,7 +386,7 @@ splices and quotations are supported.) .. ghc-flag:: -fenable-th-splice-warnings :shortdesc: Generate warnings for Template Haskell splices :type: dynamic - :reverse: -fno-enable-th-splices + :reverse: -fno-enable-th-splice-warnings :category: warnings Template Haskell splices won't be checked for warnings, because the code diff --git a/docs/users_guide/exts/type_families.rst b/docs/users_guide/exts/type_families.rst index 4843e35a80..15cf21e027 100644 --- a/docs/users_guide/exts/type_families.rst +++ b/docs/users_guide/exts/type_families.rst @@ -544,11 +544,6 @@ However see :ref:`ghci-decls` for the overlap rules in GHCi. Decidability of type synonym instances ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. extension:: UndecidableInstances - :noindex: - - Relax restrictions on the decidability of type synonym family instances. - In order to guarantee that type inference in the presence of type families is decidable, we need to place a number of additional restrictions on the formation of type instance declarations (c.f., Definition 5 @@ -577,9 +572,10 @@ as ``a ~ [F a]``, where a recursive occurrence of a type variable is underneath a family application and data constructor application - see the above mentioned paper for details. -If the option :extension:`UndecidableInstances` is passed to the compiler, the -above restrictions are not enforced and it is on the programmer to ensure -termination of the normalisation of type families during type inference. +If the option :extension:`UndecidableInstances` is passed to the compiler +(see :ref:`undecidable-instances`), the above restrictions are not enforced +and it is on the programmer to ensure termination of the normalisation +of type families during type inference. Reducing type family applications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/users_guide/exts/typed_holes.rst b/docs/users_guide/exts/typed_holes.rst index 170824ee4f..7ad2d633a5 100644 --- a/docs/users_guide/exts/typed_holes.rst +++ b/docs/users_guide/exts/typed_holes.rst @@ -300,7 +300,7 @@ configurable by a few flags. in the output. :type: dynamic :category: verbosity - :reverse: -fno-type-of-hole-fits + :reverse: -fno-show-type-of-hole-fits :default: on diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst index 78c74c5dc3..6ff9c1f20a 100644 --- a/docs/users_guide/ghci.rst +++ b/docs/users_guide/ghci.rst @@ -3303,6 +3303,7 @@ read: .. ghc-flag:: -ignore-dot-ghci :shortdesc: Disable reading of ``.ghci`` files :type: dynamic + :reverse: -no-ignore-dot-ghci :category: Don't read either :file:`./.ghci` or the other startup files when diff --git a/docs/users_guide/gone_wrong.rst b/docs/users_guide/gone_wrong.rst index 736bad36e0..5bf38a8cdb 100644 --- a/docs/users_guide/gone_wrong.rst +++ b/docs/users_guide/gone_wrong.rst @@ -38,9 +38,7 @@ When the compiler “does the wrong thing” Sensitivity to ``.hi`` interface files GHC is very sensitive about interface files. For example, if it picks up a non-standard ``Prelude.hi`` file, pretty terrible things - will happen. If you turn on - ``-XNoImplicitPrelude`` option, the compiler will - almost surely die, unless you know what you are doing. + will happen. Furthermore, as sketched below, you may have big problems running programs compiled using unstable interfaces. diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst index 2b156d7328..797b10e8fe 100644 --- a/docs/users_guide/phases.rst +++ b/docs/users_guide/phases.rst @@ -727,7 +727,7 @@ Options affecting code generation Request that GHC emits verbose symbol tables which include local symbols for module-internal functions. These can be useful for tools like - :ref:`perf ` but increase object file sizes. + `perf `__ but increase object file sizes. This is implied by :ghc-flag:`-g2 <-g>` and above. :ghc-flag:`-fno-expose-internal-symbols <-fexpose-internal-symbols>` diff --git a/docs/users_guide/profiling.rst b/docs/users_guide/profiling.rst index 62b5615aed..2463654837 100644 --- a/docs/users_guide/profiling.rst +++ b/docs/users_guide/profiling.rst @@ -429,7 +429,7 @@ compiled program. .. ghc-flag:: -fprof-auto-calls :shortdesc: Auto-add ``SCC``\\ s to all call sites :type: dynamic - :reverse: -fno-prof-auto-calls + :reverse: -fno-prof-auto :category: Adds an automatic ``SCC`` annotation to all *call sites*. This is diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst index d450fce141..ee5b1de95e 100644 --- a/docs/users_guide/using-optimisation.rst +++ b/docs/users_guide/using-optimisation.rst @@ -572,16 +572,15 @@ by saying ``-fno-wombat``. function calls. .. ghc-flag:: -fllvm-pass-vectors-in-regs - :shortdesc: Pass vector value in vector registers for function calls + :shortdesc: *(deprecated)* Does nothing :type: dynamic - :reverse: -fno-llvm-pass-vectors-in-regs :category: :default: on - Instructs GHC to use the platform's native vector registers to pass vector - arguments during function calls. As with all vector support, this requires - :ghc-flag:`-fllvm`. + This flag has no effect since GHC 8.8 - its behavior is always on. + It used to instruct GHC to use the platform's native vector registers + to pass vector arguments during function calls. .. ghc-flag:: -fmax-inline-alloc-size=⟨n⟩ :shortdesc: *default: 128.* Set the maximum size of inline array allocations diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst index 400db598ca..9b7f625bb6 100644 --- a/docs/users_guide/using-warnings.rst +++ b/docs/users_guide/using-warnings.rst @@ -640,7 +640,7 @@ of ``-W(no-)*``. .. ghc-flag:: -Wdodgy-foreign-imports :shortdesc: warn about dodgy foreign imports :type: dynamic - :reverse: -Wno-dodgy-foreign-import + :reverse: -Wno-dodgy-foreign-imports :category: Causes a warning to be emitted for foreign imports of the following @@ -1007,7 +1007,7 @@ of ``-W(no-)*``. :shortdesc: warn when a module declaration does not explicitly list all exports :type: dynamic - :reverse: -fnowarn-missing-export-lists + :reverse: -Wno-missing-export-lists :category: :since: 8.4.1 @@ -1032,7 +1032,7 @@ of ``-W(no-)*``. :shortdesc: warn when an import declaration does not explicitly list all the names brought into scope :type: dynamic - :reverse: -fnowarn-missing-import-lists + :reverse: -Wno-missing-import-lists :category: .. index:: -- cgit v1.2.1