Improve documentation for warning options
authorNathan Collins <nathan.collins@gmail.com>
Fri, 19 Oct 2018 21:44:19 +0000 (14:44 -0700)
committerBen Gamari <ben@smart-cactus.org>
Mon, 29 Oct 2018 19:11:48 +0000 (15:11 -0400)
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.

docs/users_guide/using-warnings.rst

index f0c4ac4..fe3c8cb 100644 (file)
@@ -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.