[commit: ghc] master: Clarification in the docs for INLINE (2798a17)

[git at git.haskell.org]

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

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

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

commit 2798a174296c4bc7c74b352fdcb1c775bdfc6496
Author: Simon Marlow <marlowsd at gmail.com>
Date:   Thu Sep 26 16:28:34 2013 +0100

    Clarification in the docs for INLINE
    
    People often jump to the conclusion that functions aren't inlined
    unless you say INLINE, so clarify the documentation to emphasize the
    fact that you shouldn't normally need to use INLINE unless you need to
    override the defaults.


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

2798a174296c4bc7c74b352fdcb1c775bdfc6496
 docs/users_guide/glasgow_exts.xml |   33 ++++++++++++++++++++++++++-------
 1 file changed, 26 insertions(+), 7 deletions(-)

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index c11325b..c652762 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -9244,13 +9244,32 @@ mindef ::= name
 	<title>INLINE pragma</title>
 	<indexterm><primary>INLINE</primary></indexterm>
 
-	<para>GHC (with <option>-O</option>, as always) tries to
-        inline (or “unfold”) functions/values that are
-        “small enough,” thus avoiding the call overhead
-        and possibly exposing other more-wonderful optimisations.
-        Normally, if GHC decides a function is “too
-        expensive” to inline, it will not do so, nor will it
-        export that unfolding for other modules to use.</para>
+        <para>
+          GHC (with <option>-O</option>, as always) tries to inline
+          (or “unfold”) functions/values that are
+          “small enough,” thus avoiding the call overhead
+          and possibly exposing other more-wonderful optimisations.
+          GHC has a set of heuristics, tuned over a long period of
+          time using many benchmarks, that decide when it is
+          beneficial to inline a function at its call site.  The
+          heuristics are designed to inline functions when it appears
+          to be beneficial to do so, but without incurring excessive
+          code bloat.  If a function looks too big, it won't be
+          inlined, and functions larger than a certain size will not
+          even have their definition exported in the interface file.
+          Some of the thresholds that govern these heuristic decisions
+          can be changed using flags, see <xref linkend="options-f"
+          />.
+        </para>
+
+        <para>
+          Normally GHC will do a reasonable job of deciding by itself
+          when it is a good idea to inline a function.  However,
+          sometimes you might want to override the default behaviour.
+          For example, if you have a key function that is important to
+          inline because it leads to further optimisations, but GHC
+          judges it to be too big to inline.
+        </para>
 
         <para>The sledgehammer you can bring to bear is the
         <literal>INLINE</literal><indexterm><primary>INLINE