[Git][ghc/ghc][wip/amg/warning-refactoring] 2 commits: Revise warnings documentation in user's guide
Adam Gundry (@adamgundry)
gitlab at gitlab.haskell.org
Wed Jan 11 21:30:10 UTC 2023
Adam Gundry pushed to branch wip/amg/warning-refactoring at Glasgow Haskell Compiler / GHC
Commits:
e0abd635 by Adam Gundry at 2023-01-11T21:29:39+00:00
Revise warnings documentation in user's guide
- - - - -
3d06d313 by Adam Gundry at 2023-01-11T21:29:39+00:00
Move documentation of deferred type error flags out of warnings section
- - - - -
3 changed files:
- docs/users_guide/9.6.1-notes.rst
- docs/users_guide/exts/defer_type_errors.rst
- docs/users_guide/using-warnings.rst
Changes:
=====================================
docs/users_guide/9.6.1-notes.rst
=====================================
@@ -96,6 +96,11 @@ Compiler
- The :ghc-flag:`-Woperator-whitespace` warning no longer ignores constructor symbols
(operators starting with ``:``).
+- The ``-Wno-⟨wflag⟩``, ``-Werror=⟨wflag⟩`` and ``-Wwarn=⟨wflag⟩`` options are
+ now defined systematically for all warning groups (for example,
+ ``-Wno-default``, ``-Werror=unused-binds`` and ``-Wwarn=all`` are now
+ accepted). See :ref:`options-sanity`.
+
GHCi
~~~~
=====================================
docs/users_guide/exts/defer_type_errors.rst
=====================================
@@ -34,7 +34,7 @@ to suppress these warnings.
This flag implies the :ghc-flag:`-fdefer-typed-holes` and
:ghc-flag:`-fdefer-out-of-scope-variables` flags, which enables this behaviour
-for `typed holes <#typed-holes>`__ and variables. Should you so wish, it is
+for :ref:`typed-holes` and variables. Should you so wish, it is
possible to enable :ghc-flag:`-fdefer-type-errors` without enabling
:ghc-flag:`-fdefer-typed-holes` or :ghc-flag:`-fdefer-out-of-scope-variables`,
by explicitly specifying :ghc-flag:`-fno-defer-typed-holes
@@ -42,6 +42,64 @@ by explicitly specifying :ghc-flag:`-fno-defer-typed-holes
<-fdefer-out-of-scope-variables>` on the command-line after the
:ghc-flag:`-fdefer-type-errors` flag.
+.. ghc-flag:: -fdefer-type-errors
+ :shortdesc: Turn type errors into warnings, :ref:`deferring the error until
+ runtime <defer-type-errors>`. Implies
+ :ghc-flag:`-fdefer-typed-holes` and
+ :ghc-flag:`-fdefer-out-of-scope-variables`.
+ See also :ghc-flag:`-Wdeferred-type-errors`.
+ :type: dynamic
+ :reverse: -fno-defer-type-errors
+ :category:
+
+ :since: 7.6
+
+ :implies: :ghc-flag:`-fdefer-typed-holes`, :ghc-flag:`-fdefer-out-of-scope-variables`
+
+ Defer as many type errors as possible until runtime. At compile time
+ you get a warning (instead of an error). At runtime, if you use a
+ value that depends on a type error, you get a runtime error; but you
+ can run any type-correct parts of your code just fine.
+ See also :ghc-flag:`-Wdeferred-type-errors`.
+
+.. ghc-flag:: -fdefer-typed-holes
+ :shortdesc: Convert :ref:`typed hole <typed-holes>` errors into warnings,
+ :ref:`deferring the error until runtime <defer-type-errors>`.
+ Implied by :ghc-flag:`-fdefer-type-errors`.
+ See also :ghc-flag:`-Wtyped-holes`.
+ :type: dynamic
+ :reverse: -fno-defer-typed-holes
+ :category:
+
+ :since: 7.10
+
+ Defer typed holes errors (errors about names with a leading underscore
+ (e.g., “_”, “_foo”, “_bar”)) until runtime. This will turn the errors
+ produced by :ref:`typed holes <typed-holes>` into warnings. Using a value
+ that depends on a typed hole produces a runtime error, the same as
+ :ghc-flag:`-fdefer-type-errors` (which implies this option). See :ref:`typed-holes`.
+
+ Implied by :ghc-flag:`-fdefer-type-errors`. See also :ghc-flag:`-Wtyped-holes`.
+
+.. ghc-flag:: -fdefer-out-of-scope-variables
+ :shortdesc: Convert variable out of scope variables errors into warnings.
+ Implied by :ghc-flag:`-fdefer-type-errors`.
+ See also :ghc-flag:`-Wdeferred-out-of-scope-variables`.
+ :type: dynamic
+ :reverse: -fno-defer-out-of-scope-variables
+ :category:
+
+ :since: 8.0
+
+ Defer variable out-of-scope errors (errors about names without a leading underscore)
+ until runtime. This will turn variable-out-of-scope errors into warnings.
+ Using a value that depends on an out-of-scope variable produces a runtime error,
+ the same as :ghc-flag:`-fdefer-type-errors` (which implies this option).
+ See :ref:`typed-holes`.
+
+ Implied by :ghc-flag:`-fdefer-type-errors`. See also :ghc-flag:`-Wdeferred-out-of-scope-variables`.
+
+
At runtime, whenever a term containing a type error would need to be
evaluated, the error is converted into a runtime exception of type
``TypeError``. Note that type errors are deferred as much as possible
=====================================
docs/users_guide/using-warnings.rst
=====================================
@@ -11,20 +11,31 @@ GHC has a number of options that select which types of non-fatal error
messages, otherwise known as warnings, can be generated during compilation.
Some options control individual warnings and others control collections
of warnings.
-To turn off an individual warning ``-W<wflag>``, use ``-Wno-<wflag>``.
-To reverse ``-Werror``, which makes all warnings into errors, use ``-Wwarn``.
+Use ``-W⟨wflag⟩`` to turn on an individual warning or a collection, or use
+``-Wno-⟨wflag⟩`` to turn it off.
+Use ``-Werror`` to make all warnings into fatal errors, or ``-Werror=⟨wflag⟩`` to
+make a specific warning into an error. Reverse this with ``-Wwarn`` to make all
+warnings non-fatal, or ``-Wwarn=⟨wflag⟩`` to make a specific warning non-fatal.
.. note::
- In GHC < 8 the syntax for ``-W<wflag>`` was ``-fwarn-<wflag>``
+ In GHC < 8 the syntax for ``-W⟨wflag⟩`` was ``-fwarn-⟨wflag⟩``
(e.g. ``-fwarn-incomplete-patterns``).
This spelling is deprecated, but still accepted for backwards compatibility.
- Likewise, ``-Wno-<wflag>`` used to be ``fno-warn-<wflag>``
+ Likewise, ``-Wno-⟨wflag⟩`` used to be ``fno-warn-⟨wflag⟩``
(e.g. ``-fno-warn-incomplete-patterns``).
+Warning groups
+==============
+
+The following flags are simple ways to select standard "packages" of
+warnings. They can be reversed using ``-Wno-⟨group⟩``, which has the same effect
+as ``-Wno-...`` for every individual warning in the group.
+
.. ghc-flag:: -Wdefault
:shortdesc: enable default flags
:type: dynamic
+ :reverse: -Wno-default
:category:
:since: 8.0
@@ -67,12 +78,10 @@ To reverse ``-Werror``, which makes all warnings into errors, use ``-Wwarn``.
* :ghc-flag:`-Wgadt-mono-local-binds`
* :ghc-flag:`-Wtype-equality-requires-operators`
-The following flags are simple ways to select standard "packages" of warnings:
-
.. ghc-flag:: -W
:shortdesc: enable normal warnings
:type: dynamic
- :reverse: -w
+ :reverse: -Wno-extra
:category:
Provides the standard warnings plus
@@ -92,14 +101,14 @@ The following flags are simple ways to select standard "packages" of warnings:
.. ghc-flag:: -Wextra
:shortdesc: alias for :ghc-flag:`-W`
:type: dynamic
- :reverse: -w
+ :reverse: -Wno-extra
Alias for :ghc-flag:`-W`
.. ghc-flag:: -Wall
:shortdesc: enable almost all warnings (details in :ref:`options-sanity`)
:type: dynamic
- :reverse: -w
+ :reverse: -Wno-all
:category:
Turns on all warning options that indicate potentially suspicious
@@ -133,6 +142,7 @@ The following flags are simple ways to select standard "packages" of warnings:
.. ghc-flag:: -Weverything
:shortdesc: enable all warnings supported by GHC
:type: dynamic
+ :reverse: -w
:category:
:since: 8.0
@@ -164,14 +174,6 @@ The following flags are simple ways to select standard "packages" of warnings:
* :ghc-flag:`-Wcompat-unqualified-imports`
* :ghc-flag:`-Wtype-equality-out-of-scope`
-.. ghc-flag:: -Wno-compat
- :shortdesc: Disables all warnings enabled by :ghc-flag:`-Wcompat`.
- :type: dynamic
- :reverse: -Wcompat
- :category:
-
- Disables all warnings enabled by :ghc-flag:`-Wcompat`.
-
.. ghc-flag:: -w
:shortdesc: disable all warnings
:type: dynamic
@@ -186,6 +188,24 @@ The following flags are simple ways to select standard "packages" of warnings:
Deprecated alias for :ghc-flag:`-w`
+When a warning is emitted, the specific warning flag which controls
+it is shown, but the group can optionally be shown as well:
+
+.. ghc-flag:: -fshow-warning-groups
+ :shortdesc: show which group an emitted warning belongs to.
+ :type: dynamic
+ :reverse: -fno-show-warning-groups
+ :category:
+
+ :default: off
+
+ When showing which flag controls a warning, also show the
+ respective warning group flag(s) that warning is contained in.
+
+
+Treating warnings as fatal errors
+=================================
+
These options control which warnings are considered fatal and cause compilation
to abort.
@@ -199,7 +219,7 @@ to abort.
Makes any warning into a fatal error. Useful so that you don't miss
warnings when doing batch compilation. To reverse ``-Werror`` and stop
- treating any warnings as errors use ``-Wwarn``, or use ``-Wwarn=<wflag>``
+ treating any warnings as errors use ``-Wwarn``, or use ``-Wwarn=⟨wflag⟩``
to stop treating specific warnings as errors.
.. ghc-flag:: -Werror=⟨wflag⟩
@@ -209,13 +229,14 @@ to abort.
:category:
:noindex:
- :implies: ``-W<wflag>``
+ :implies: ``-W⟨wflag⟩``
Makes a specific warning into a fatal error. The warning will be enabled if
- it hasn't been enabled yet. Can be reversed with ``-Wwarn=<wflag>``.
+ it hasn't been enabled yet. Can be reversed with ``-Wwarn=⟨wflag⟩``.
- ``-Werror=compat`` has the same effect as ``-Werror=...`` for each warning
- flag in the :ghc-flag:`-Wcompat` option group.
+ ``-Werror=⟨group⟩`` has the same effect as ``-Werror=...`` for each warning
+ flag in the group (for example, ``-Werror=compat`` will turn every warning
+ in the :ghc-flag:`-Wcompat` group into a fatal error).
.. ghc-flag:: -Wwarn
:shortdesc: make warnings non-fatal
@@ -235,25 +256,25 @@ to abort.
Causes a specific warning to be treated as normal warning, not fatal error.
- Note that it doesn't fully negate the effects of ``-Werror=<wflag>`` - the
+ Note that it doesn't fully negate the effects of ``-Werror=⟨wflag⟩`` - the
warning will still be enabled.
- ``-Wwarn=compat`` has the same effect as ``-Wwarn=...`` for each warning
- flag in the :ghc-flag:`-Wcompat` option group.
-
-When a warning is emitted, the specific warning flag which controls
-it is shown.
+ ``-Wwarn=⟨group⟩`` has the same effect as ``-Wwarn=...`` for each warning
+ flag in the group (for example, ``-Wwarn=compat`` will mark every warning in
+ the :ghc-flag:`-Wcompat` group as non-fatal).
-.. ghc-flag:: -fshow-warning-groups
- :shortdesc: show which group an emitted warning belongs to.
+.. ghc-flag:: -Wno-error=⟨wflag⟩
+ :shortdesc: make a specific warning non-fatal
:type: dynamic
- :reverse: -fno-show-warning-groups
+ :reverse: -Werror=⟨wflag⟩
:category:
+ :noindex:
- :default: off
+ Alternative spelling for ``-Wwarn=⟨wflag⟩``.
- When showing which flag controls a warning, also show the
- respective warning group flag(s) that warning is contained in.
+
+Individual warning options
+==========================
The full set of warning options is described below. To turn off any
warning, simply give the corresponding ``-Wno-...`` option on the
@@ -322,7 +343,7 @@ of ``-W(no-)*``.
Determines whether the compiler reports typed holes warnings. Has no
effect unless typed holes errors are deferred until runtime. See
- :ref:`typed-holes` and :ref:`defer-type-errors`
+ :ref:`typed-holes` and :ref:`defer-type-errors`.
.. ghc-flag:: -Wdeferred-type-errors
:shortdesc: Report warnings when :ref:`deferred type errors
@@ -332,70 +353,12 @@ of ``-W(no-)*``.
:reverse: -Wno-deferred-type-errors
:category:
- :since: 8.4
+ :since: 8.0
:default: on
Causes a warning to be reported when a type error is deferred until
- runtime. See :ref:`defer-type-errors`
-
-.. ghc-flag:: -fdefer-type-errors
- :shortdesc: Turn type errors into warnings, :ref:`deferring the error until
- runtime <defer-type-errors>`. Implies
- :ghc-flag:`-fdefer-typed-holes` and
- :ghc-flag:`-fdefer-out-of-scope-variables`.
- See also :ghc-flag:`-Wdeferred-type-errors`
- :type: dynamic
- :reverse: -fno-defer-type-errors
- :category:
-
- :since: 7.6
-
- :implies: :ghc-flag:`-fdefer-typed-holes`, :ghc-flag:`-fdefer-out-of-scope-variables`
-
- Defer as many type errors as possible until runtime. At compile time
- you get a warning (instead of an error). At runtime, if you use a
- value that depends on a type error, you get a runtime error; but you
- can run any type-correct parts of your code just fine. See
- :ref:`defer-type-errors`
-
-.. ghc-flag:: -fdefer-typed-holes
- :shortdesc: Convert :ref:`typed hole <typed-holes>` errors into warnings,
- :ref:`deferring the error until runtime <defer-type-errors>`.
- Implied by :ghc-flag:`-fdefer-type-errors`.
- See also :ghc-flag:`-Wtyped-holes`.
- :type: dynamic
- :reverse: -fno-defer-typed-holes
- :category:
-
- :since: 7.10
-
- Defer typed holes errors (errors about names with a leading underscore
- (e.g., “_”, “_foo”, “_bar”)) until runtime. This will turn the errors
- produced by :ref:`typed holes <typed-holes>` into warnings. Using a value
- that depends on a typed hole produces a runtime error, the same as
- :ghc-flag:`-fdefer-type-errors` (which implies this option). See :ref:`typed-holes`
- and :ref:`defer-type-errors`.
-
- Implied by :ghc-flag:`-fdefer-type-errors`. See also :ghc-flag:`-Wtyped-holes`.
-
-.. ghc-flag:: -fdefer-out-of-scope-variables
- :shortdesc: Convert variable out of scope variables errors into warnings.
- Implied by :ghc-flag:`-fdefer-type-errors`.
- See also :ghc-flag:`-Wdeferred-out-of-scope-variables`.
- :type: dynamic
- :reverse: -fno-defer-out-of-scope-variables
- :category:
-
- :since: 8.0
-
- Defer variable out-of-scope errors (errors about names without a leading underscore)
- until runtime. This will turn variable-out-of-scope errors into warnings.
- Using a value that depends on an out-of-scope variable produces a runtime error,
- the same as :ghc-flag:`-fdefer-type-errors` (which implies this option).
- See :ref:`typed-holes` and :ref:`defer-type-errors`.
-
- Implied by :ghc-flag:`-fdefer-type-errors`. See also :ghc-flag:`-Wdeferred-out-of-scope-variables`.
+ runtime. See :ref:`defer-type-errors`.
.. ghc-flag:: -Wdeferred-out-of-scope-variables
:shortdesc: Report warnings when variable out-of-scope errors are
@@ -408,6 +371,7 @@ of ``-W(no-)*``.
:since: 8.0
Warn when a deferred out-of-scope variable is encountered.
+ See :ref:`defer-type-errors`.
.. ghc-flag:: -Wpartial-type-signatures
:shortdesc: warn about holes in partial type signatures when
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/66c7c3aa14a2d63806e0f2e1e76fbb390b0a0895...3d06d31347f6f3d3a1c34309ed63bca8d7032d05
--
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/66c7c3aa14a2d63806e0f2e1e76fbb390b0a0895...3d06d31347f6f3d3a1c34309ed63bca8d7032d05
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/20230111/c21e9370/attachment-0001.html>
More information about the ghc-commits
mailing list