[commit: ghc] master: Tidy up and improve comments about one-shot info (ee56dc5)

[git at git.haskell.org]

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

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

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

commit ee56dc56a4a0f556894c4d2bd04c3d4ca73e95a1
Author: Simon Peyton Jones <simonpj at microsoft.com>
Date:   Tue Mar 3 21:52:28 2015 +0000

    Tidy up and improve comments about one-shot info
    
    (Triggered by investigating Trac #10102 etc.)


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

ee56dc56a4a0f556894c4d2bd04c3d4ca73e95a1
 compiler/basicTypes/BasicTypes.hs | 2 +-
 compiler/basicTypes/Demand.hs     | 5 ++---
 compiler/basicTypes/MkId.hs       | 9 +++++----
 compiler/coreSyn/CoreTidy.hs      | 3 +--
 compiler/iface/IfaceType.hs       | 4 ++--
 5 files changed, 11 insertions(+), 12 deletions(-)

diff --git a/compiler/basicTypes/BasicTypes.hs b/compiler/basicTypes/BasicTypes.hs
index 04353bf..973666d 100644
--- a/compiler/basicTypes/BasicTypes.hs
+++ b/compiler/basicTypes/BasicTypes.hs
@@ -163,7 +163,7 @@ type Alignment = Int -- align to next N-byte boundary (N must be a power of 2).
 data OneShotInfo
   = NoOneShotInfo -- ^ No information
   | ProbOneShot   -- ^ The lambda is probably applied at most once
-                  -- See Note [Computing one-shot info, and ProbOneShot] in OccurAnl
+                  -- See Note [Computing one-shot info, and ProbOneShot] in Demand
   | OneShotLam    -- ^ The lambda is applied at most once.
   deriving (Eq)
 
diff --git a/compiler/basicTypes/Demand.hs b/compiler/basicTypes/Demand.hs
index ecf22bc..3ca7c2d 100644
--- a/compiler/basicTypes/Demand.hs
+++ b/compiler/basicTypes/Demand.hs
@@ -1618,9 +1618,8 @@ argOneShots one_shot_info (JD { absd = usg })
     go (UCall Many u) = NoOneShotInfo : go u
     go _              = []
 
-{-
-Note [Computing one-shot info, and ProbOneShot]
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+{- Note [Computing one-shot info, and ProbOneShot]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Consider a call
     f (\pqr. e1) (\xyz. e2) e3
 where f has usage signature
diff --git a/compiler/basicTypes/MkId.hs b/compiler/basicTypes/MkId.hs
index 0b22a64..c4222be 100644
--- a/compiler/basicTypes/MkId.hs
+++ b/compiler/basicTypes/MkId.hs
@@ -1250,7 +1250,6 @@ appears un-applied, we'll end up just calling it.
 
 Note [The oneShot function]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 In the context of making left-folds fuse somewhat okish (see ticket #7994
 and Note [Left folds via right fold]) it was determined that it would be useful
 if library authors could explicitly tell the compiler that a certain lambda is
@@ -1270,9 +1269,11 @@ after unfolding the definition `oneShot = \f \x[oneshot]. f x` we get
  --> \x[oneshot] e[x/y]
 which is what we want.
 
-It is only effective if this bits survives as long as possible and makes it into
-the interface in unfoldings (See Note [Preserve OneShotInfo]). Also see
-https://ghc.haskell.org/trac/ghc/wiki/OneShot.
+It is only effective if the one-shot info survives as long as possible; in
+particular it must make it into the interface in unfoldings. See Note [Preserve
+OneShotInfo] in CoreTidy.
+
+Also see https://ghc.haskell.org/trac/ghc/wiki/OneShot.
 
 
 Note [magicDictId magic]
diff --git a/compiler/coreSyn/CoreTidy.hs b/compiler/coreSyn/CoreTidy.hs
index 325950c..4ee867a 100644
--- a/compiler/coreSyn/CoreTidy.hs
+++ b/compiler/coreSyn/CoreTidy.hs
@@ -258,12 +258,11 @@ but that seems more indirect and surprising.)
 
 Note [Preserve OneShotInfo]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 We keep the OneShotInfo because we want it to propagate into the interface.
 Not all OneShotInfo is determined by a compiler analysis; some is added by a
 call of GHC.Exts.oneShot, which is then discarded before the end of the
 optimisation pipeline, leaving only the OneShotInfo on the lambda. Hence we
-must preserve this info in inlinings.
+must preserve this info in inlinings. See Note [The oneShot function] in MkId.
 
 This applies to lambda binders only, hence it is stored in IfaceLamBndr.
 -}
diff --git a/compiler/iface/IfaceType.hs b/compiler/iface/IfaceType.hs
index fed3ffc..e83c25e 100644
--- a/compiler/iface/IfaceType.hs
+++ b/compiler/iface/IfaceType.hs
@@ -87,8 +87,8 @@ type IfaceIdBndr  = (IfLclName, IfaceType)
 type IfaceTvBndr  = (IfLclName, IfaceKind)
 
 
-data IfaceOneShot    -- see Note [Preserve OneShotInfo]
-  = IfaceNoOneShot
+data IfaceOneShot    -- See Note [Preserve OneShotInfo] in CoreTicy
+  = IfaceNoOneShot   -- and Note [The oneShot function] in MkId
   | IfaceOneShot
 
 type IfaceLamBndr