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

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 7c1e65a250..2e509e1e2d 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 2c0e54883a..33af295f1b 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 10d0a638f0..634482a42c 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>