[commit: ghc] master: Update userguide for new `-fwarn-trustworthy-safe` flag. (8fe2bbe)

[git at git.haskell.org]

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

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

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

commit 8fe2bbe9502b4accafb14a4234f264f4457f3ff2
Author: David Terei <code at davidterei.com>
Date:   Wed Nov 12 18:39:01 2014 -0800

    Update userguide for new `-fwarn-trustworthy-safe` flag.


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

8fe2bbe9502b4accafb14a4234f264f4457f3ff2
 docs/users_guide/7.10.1-notes.xml | 30 ++++++++++++++++++++++++++++++
 docs/users_guide/flags.xml        | 21 +++++++++++++++++++--
 docs/users_guide/safe_haskell.xml | 11 ++++++++++-
 3 files changed, 59 insertions(+), 3 deletions(-)

diff --git a/docs/users_guide/7.10.1-notes.xml b/docs/users_guide/7.10.1-notes.xml
index 7c1e65a..2e509e1 100644
--- a/docs/users_guide/7.10.1-notes.xml
+++ b/docs/users_guide/7.10.1-notes.xml
@@ -91,6 +91,36 @@
                 </para>
            </listitem>
            <listitem>
+                <para>
+                    A new warning flag, <option>-fwarn-trustworthy-safe</option>
+                    has been added and is turned on with
+                    <option>-Wall</option>. It warns when a module that is
+                    compiled with <option>-XTrustworthy</option> is actually
+                    infered as an <option>-XSafe</option> module. This lets the
+                    module author know that they can tighten their Safe Haskell
+                    bounds if desired.
+                </para>
+           </listitem>
+           <listitem>
+                <para>
+                    The <option>-fwarn-safe</option> and
+                    <option>-fwarn-unsafe</option> that warn if a module was
+                    infered as Safe or Unsafe have been improved to work with
+                    all Safe Haskell module types. Previously, they only worked
+                    for unmarked modules where the compiler was infering the
+                    modules Safe Haskell type. They now work even for modules
+                    marked as <option>-XTrustworthy</option> or
+                    <option>-XUnsafe</option>. This is useful either to have
+                    GHC check your assumptions, or to generate a list of
+                    reasons easily why a module is regarded as Unsafe.
+                </para>
+                <para>
+                    For many use cases, the new
+                    <option>-fwarn-trustworthy-safe</option> flag is better
+                    suited than either of these two.
+                </para>
+           </listitem>
+           <listitem>
              <para>
                <option>-ddump-simpl-phases</option> and
                <option>-ddump-core-pipeline</option> flags have been removed.
diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index 2c0e548..33af295 100644
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -1565,7 +1565,10 @@
             <entry><option>-fwarn-unsafe</option></entry>
             <entry>warn if the module being compiled is regarded to be unsafe.
               Should be used to check the safety status of modules when using safe
-              inference.</entry>
+              inference. Works on all module types, even those using explicit
+              <link linkend="safe-haskell">Safe Haskell</link> modes (such as
+              <option>-XTrustworthy</option>) and so can be used to have the
+              compiler check any assumptions made.</entry>
             <entry>dynamic</entry>
             <entry><option>-fno-warn-unsafe</option></entry>
           </row>
@@ -1574,7 +1577,21 @@
             <entry><option>-fwarn-safe</option></entry>
             <entry>warn if the module being compiled is regarded to be safe.
               Should be used to check the safety status of modules when using safe
-              inference.</entry>
+              inference. Works on all module types, even those using explicit
+              <link linkend="safe-haskell">Safe Haskell</link> modes (such as
+              <option>-XTrustworthy</option>) and so can be used to have the
+              compiler check any assumptions made.</entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-warn-safe</option></entry>
+          </row>
+
+          <row>
+            <entry><option>-fwarn-trustworthy-safe</option></entry>
+            <entry>warn if the module being compiled is marked as
+              <option>-XTrustworthy</option> but it could instead be marked as
+              <option>-XSafe</option>, a more informative bound. Can be used to
+              detect once a Safe Haskell bound can be improved as dependencies
+              are updated.</entry>
             <entry>dynamic</entry>
             <entry><option>-fno-warn-safe</option></entry>
           </row>
diff --git a/docs/users_guide/safe_haskell.xml b/docs/users_guide/safe_haskell.xml
index 10d0a63..634482a 100644
--- a/docs/users_guide/safe_haskell.xml
+++ b/docs/users_guide/safe_haskell.xml
@@ -705,7 +705,7 @@
       </varlistentry>
     </variablelist>
 
-    And two warning flags:
+    And three warning flags:
 
     <variablelist>
       <varlistentry>
@@ -724,6 +724,15 @@
           when using safe inference.
         </listitem>
       </varlistentry>
+      <varlistentry>
+        <term>-fwarn-trustworthy-safe</term>
+        <indexterm><primary>-fwarn-trustworthy-safe</primary></indexterm>
+        <listitem>Issue a warning if the module being compiled is marked as
+          <option>-XTrustworthy</option> but it could instead be marked as
+          <option>-XSafe</option>, a more informative bound. Can be used to
+          detect once a Safe Haskell bound can be improved as dependencies are
+          updated.</listitem>
+      </varlistentry>
     </variablelist>
   </sect2>