[commit: ghc] master: Improve documentation for warning options (b8e30e4)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/b8e30e40b08db3dd50e7a972a4969c8f8f784eaa/ghc

>---------------------------------------------------------------

commit b8e30e40b08db3dd50e7a972a4969c8f8f784eaa
Author: Nathan Collins <nathan.collins at gmail.com>
Date:   Fri Oct 19 14:44:19 2018 -0700

    Improve documentation for warning options
    
    My main goal was to make it easy to discover how to reverse `-Werror`,
    since `Wno-error` doesn't work, and the fact that `-Wwarn` negates
    `-Werror` was only mentioned in the `-Wwarn` docs before.
    
    Other changes:
    - explain at the outset that some options control individual warnings
      while others control warning families.
    - explain at the outset that `-Wno-<wflag>` can be used to reverse
      `-W<wflag>`. This is no mentioned in two places, but I don't think
      that's a bad thing.


>---------------------------------------------------------------

b8e30e40b08db3dd50e7a972a4969c8f8f784eaa
 docs/users_guide/using-warnings.rst | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst
index f0c4ac4..fe3c8cb 100644
--- a/docs/users_guide/using-warnings.rst
+++ b/docs/users_guide/using-warnings.rst
@@ -8,8 +8,13 @@ Warnings and sanity-checking
    single: warnings
 
 GHC has a number of options that select which types of non-fatal error
-messages, otherwise known as warnings, can be generated during
-compilation. By default, you get a standard set of warnings which are
+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``.
+
+By default, you get a standard set of warnings which are
 generally likely to indicate bugs in your program. These are:
 
 .. hlist::
@@ -146,7 +151,9 @@ to abort.
     :category:
 
     Makes any warning into a fatal error. Useful so that you don't miss
-    warnings when doing batch compilation.
+    warnings when doing batch compilation. To reverse ``-Werror`` and stop
+    treating any warnings as errors use ``-Wwarn``, or use ``-Wwarn=<wflag>``
+    to stop treating specific warnings as errors.
 
 .. ghc-flag:: -Werror=⟨wflag⟩
     :shortdesc: make a specific warning fatal
@@ -158,7 +165,7 @@ to abort.
     :implies: ``-W<wflag>``
 
     Makes a specific warning into a fatal error. The warning will be enabled if
-    it hasn't been enabled yet.
+    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.