Tidy up and improve comments about one-shot info

(Triggered by investigating Trac #10102 etc.)

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)
 

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

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]

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.
 -}

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