[commit: ghc] master: Document -fwarn-inline-rule-shadowing (Trac #9166) (52509d8)

[git at git.haskell.org]

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

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

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

commit 52509d8f07f64c95ff4f6090755f51992c501d0c
Author: Simon Peyton Jones <simonpj at microsoft.com>
Date:   Mon Jun 9 13:59:42 2014 +0100

    Document -fwarn-inline-rule-shadowing (Trac #9166)


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

52509d8f07f64c95ff4f6090755f51992c501d0c
 docs/users_guide/glasgow_exts.xml | 11 +++++++++--
 docs/users_guide/using.xml        | 10 ++++++++++
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index ac8004f..0c3dd46 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -10912,8 +10912,8 @@ not be substituted, and the rule would not fire.
 
 </sect2>
 
-<sect2 id="conlike">
-<title>How rules interact with INLINE/NOINLINE and CONLIKE pragmas</title>
+<sect2 id="rules-inline">
+<title>How rules interact with INLINE/NOINLINE pragmas</title>
 
 <para>
 Ordinary inlining happens at the same time as rule rewriting, which may lead to unexpected
@@ -10939,7 +10939,14 @@ would have been a better chance that <literal>f</literal>'s RULE might fire.
 The way to get predictable behaviour is to use a NOINLINE
 pragma, or an INLINE[<replaceable>phase</replaceable>] pragma, on <literal>f</literal>, to ensure
 that it is not inlined until its RULEs have had a chance to fire.
+The warning flag <option>-fwarn-inline-rule-shadowing</option> (see <xref linkend="options-sanity"/>)
+warns about this situation.
 </para>
+</sect2>
+
+<sect2 id="conlike">
+<title>How rules interact with CONLIKE pragmas</title>
+
 <para>
 GHC is very cautious about duplicating work.  For example, consider
 <programlisting>
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index e404d07..921d5a3 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -1866,6 +1866,16 @@ _  = rhs3        -- No warning: lone wild-card pattern
         </listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>-fwarn-inline-rule-shadowing</option>:</term>
+        <listitem>
+          <indexterm><primary><option>-fwarn-inline-rule-shadowing</option></primary></indexterm>
+          <para>Warn if a rewrite RULE might fail to fire because the function might be
+                inlined before the rule has a chance to fire.  See <xref linkend="rules-inline"/>.
+              </para>
+        </listitem>
+      </varlistentry>
+
     </variablelist>
 
     <para>If you're feeling really paranoid, the