[commit: ghc] master: Comments only, relating to #8166 fix (ef01794)

[git at git.haskell.org]

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

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

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

commit ef017944600cf4e153aad686a6a78bfb48dea67a
Author: Simon Peyton Jones <simonpj at microsoft.com>
Date:   Tue Aug 27 15:48:02 2013 +0100

    Comments only, relating to #8166 fix


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

ef017944600cf4e153aad686a6a78bfb48dea67a
 compiler/codeGen/StgCmm.hs      |    7 ++-----
 compiler/codeGen/StgCmmExpr.hs  |    7 ++++---
 compiler/codeGen/StgCmmMonad.hs |   10 +++++++++-
 3 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/compiler/codeGen/StgCmm.hs b/compiler/codeGen/StgCmm.hs
index 8b3bac3..9b1bce4 100644
--- a/compiler/codeGen/StgCmm.hs
+++ b/compiler/codeGen/StgCmm.hs
@@ -257,13 +257,10 @@ cgDataCon data_con
 --      Stuff to support splitting
 ---------------------------------------------------------------
 
--- If we're splitting the object, we need to externalise all the
--- top-level names (and then make sure we only use the externalised
--- one in any C label we use which refers to this name).
-
 maybeExternaliseId :: DynFlags -> Id -> FCode Id
 maybeExternaliseId dflags id
-  | gopt Opt_SplitObjs dflags,  -- Externalise the name for -split-objs
+  | gopt Opt_SplitObjs dflags,  -- See Note [Externalise when splitting]
+                                -- in StgCmmMonad
     isInternalName name = do { mod <- getModuleName
                              ; returnFC (setIdName id (externalise mod)) }
   | otherwise           = returnFC id
diff --git a/compiler/codeGen/StgCmmExpr.hs b/compiler/codeGen/StgCmmExpr.hs
index 6b010bb..c062369 100644
--- a/compiler/codeGen/StgCmmExpr.hs
+++ b/compiler/codeGen/StgCmmExpr.hs
@@ -635,9 +635,10 @@ cgIdApp fun_id args = do
     dflags   <- getDynFlags
     fun_info <- getCgIdInfo fun_id
     let cg_fun_id   = cg_id fun_info
-        -- NB. use (cg_id fun_info) instead of fun_id, because the former
-        -- may be externalised for -split-objs.
-        -- See StgCmm.maybeExternaliseId.
+           -- NB: use (cg_id fun_info) instead of fun_id, because
+           -- the former may be externalised for -split-objs.
+           -- See Note [Externalise when splitting] in StgCmmMonad
+
         fun_arg     = StgVarArg cg_fun_id
         fun_name    = idName            cg_fun_id
         fun         = idInfoToAmode     fun_info
diff --git a/compiler/codeGen/StgCmmMonad.hs b/compiler/codeGen/StgCmmMonad.hs
index 17bad24..d5e893a 100644
--- a/compiler/codeGen/StgCmmMonad.hs
+++ b/compiler/codeGen/StgCmmMonad.hs
@@ -180,13 +180,21 @@ type CgBindings = IdEnv CgIdInfo
 
 data CgIdInfo
   = CgIdInfo
-        { cg_id :: Id        -- Id that this is the info for
+        { cg_id :: Id   -- Id that this is the info for
                         -- Can differ from the Id at occurrence sites by
                         -- virtue of being externalised, for splittable C
+                        -- See Note [Externalise when splitting]
         , cg_lf  :: LambdaFormInfo
         , cg_loc :: CgLoc                     -- CmmExpr for the *tagged* value
         }
 
+-- Note [Externalise when splitting]
+-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-- If we're splitting the object with -fsplit-objs, we need to
+-- externalise *all* the top-level names, and then make sure we only
+-- use the externalised one in any C label we use which refers to this
+-- name.
+
 data CgLoc
   = CmmLoc CmmExpr        -- A stable CmmExpr; that is, one not mentioning
                         -- Hp, so that it remains valid across calls