[commit: ghc-prim] master: Merge documentation from inline's old primop entry (97961bc)

[Ian Lynagh]

Repository : ssh://darcs.haskell.org//srv/darcs/packages/ghc-prim

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/97961bcdb8c7e6c221389e030bb1ac77ee64786f

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

commit 97961bcdb8c7e6c221389e030bb1ac77ee64786f
Author: Ian Lynagh <ian at well-typed.com>
Date:   Tue Nov 13 19:44:34 2012 +0000

    Merge documentation from inline's old primop entry

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

 GHC/Magic.hs |   22 ++++++++++++++++------
 1 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/GHC/Magic.hs b/GHC/Magic.hs
index e66f547..969067f 100644
--- a/GHC/Magic.hs
+++ b/GHC/Magic.hs
@@ -19,12 +19,22 @@
 
 module GHC.Magic ( inline ) where
 
--- | The call '(inline f)' reduces to 'f', but 'inline' has a BuiltInRule
--- that tries to inline 'f' (if it has an unfolding) unconditionally
--- The 'NOINLINE' pragma arranges that inline only gets inlined (and
--- hence eliminated) late in compilation, after the rule has had
--- a good chance to fire.
-inline :: a -> a
+-- | The call '(inline f)' arranges that 'f' is inlined, regardless of
+-- its size. More precisely, the call '(inline f)' rewrites to the
+-- right-hand side of 'f'\'s definition. This allows the programmer to
+-- control inlining from a particular call site rather than the
+-- definition site of the function (c.f. 'INLINE' pragmas).
+--
+-- This inlining occurs regardless of the argument to the call or the
+-- size of 'f'\'s definition; it is unconditional. The main caveat is
+-- that 'f'\'s definition must be visible to the compiler; it is
+-- therefore recommended to mark the function with an 'INLINABLE'
+-- pragma at its definition so that GHC guarantees to record its
+-- unfolding regardless of size.
+--
+-- If no inlining takes place, the 'inline' function expands to the
+-- identity function in Phase zero, so its use imposes no overhead.
 {-# NOINLINE[0] inline #-}
+inline :: a -> a
 inline x = x