Add comments about TH levels

compiler/typecheck/TcExpr.hs

@@ -1957,6 +1957,9 @@ too_many_args fun args
 -}
 
 checkThLocalId :: Id -> TcM ()
+-- The renamer has already done checkWellStaged,
+--   in RnSplice.checkThLocalName, so don't repeat that here.
+-- Here we just just add constraints fro cross-stage lifting
 checkThLocalId id
   = do  { mb_local_use <- getStageAndBindLevel (idName id)
         ; case mb_local_use of
@@ -1973,7 +1976,6 @@ checkCrossStageLifting :: TopLevelFlag -> Id -> ThStage -> TcM ()
 -- we must check whether there's a cross-stage lift to do
 -- Examples   \x -> [|| x ||]
 --            [|| map ||]
--- There is no error-checking to do, because the renamer did that
 --
 -- This is similar to checkCrossStageLifting in GHC.Rename.Splice, but
 -- this code is applied to *typed* brackets.

compiler/typecheck/TcRnTypes.hs

@@ -911,7 +911,12 @@ removeBindingShadowing bindings = reverse $ fst $ foldl
 
 data SpliceType = Typed | Untyped
 
-data ThStage    -- See Note [Template Haskell state diagram] in TcSplice
+data ThStage    -- See Note [Template Haskell state diagram]
+                -- and Note [Template Haskell levels] in TcSplice
+    -- Start at:   Comp
+    -- At bracket: wrap current stage in Brack
+    -- At splice:  currently Brack: return to previous stage
+    --             currently Comp/Splice: compile and run
   = Splice SpliceType -- Inside a top-level splice
                       -- This code will be run *at compile time*;
                       --   the result replaces the splice
@@ -980,11 +985,10 @@ outerLevel = 1  -- Things defined outside brackets
 
 thLevel :: ThStage -> ThLevel
 thLevel (Splice _)    = 0
-thLevel (RunSplice _) =
-    -- See Note [RunSplice ThLevel].
-    panic "thLevel: called when running a splice"
 thLevel Comp          = 1
 thLevel (Brack s _)   = thLevel s + 1
+thLevel (RunSplice _) = panic "thLevel: called when running a splice"
+                        -- See Note [RunSplice ThLevel].
 
 {- Node [RunSplice ThLevel]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

compiler/typecheck/TcSplice.hs

@@ -466,7 +466,7 @@ Note [Template Haskell levels]
                incremented by brackets [| |]
                incremented by name-quoting 'f
 
-When a variable is used, we compare
+* When a variable is used, checkWellStaged compares
         bind:  binding level, and
         use:   current level at usage site