Apply 3 suggestion(s) to 1 file(s)

compiler/GHC/Tc/Gen/Splice.hs

@@ -2931,15 +2931,9 @@ tcGetInterp = do
 --   stage(N+1) compiler: The result of compiling GHC from source with stage(N)
 --       Recall that any code compiled by the stage1 compiler should be binary
 --       identical to the same code compiled by later stages.
---   boot TH: the `template-haskell` that comes with (and is linked to) the
+--   boot `ghc-boot-th`: the `ghc-boot-th` that comes with (and is linked to) the
 --       boot/stage0 compiler
---   in-tree TH: the `template-haskell` library that lives in GHC's repository.
---       Recall that building in-tree TH with the stage1 compiler yields a binary
---       that is identical to the in-tree TH compiled by stage2.
---   boot library: A library such as bytestring or containers that GHC depends on.
---       CONFUSINGLY, we build these libraries with the boot compiler as well as
---       the stage1 compiler; thus the "boot" in boot library does not refer to a
---       stage.
+--   in-tree `ghc-boot-th`: the `ghc-boot-th` library that lives in GHC's repository.
 --
 -- Here is how we bootstrap TH in tandem with GHC:
 --
@@ -2951,7 +2945,10 @@ tcGetInterp = do
 --     re-exposes the TH modules from `ghc-internal`.
 --  4. Build and link the stage2 compiler against the in-tree TH.
 --
--- (Rejected) alternative designs:
+-- When we decided in favour of the current design, `template-haskell`
+-- still contained the wired-in Ids that meanwhile were moved to
+-- `ghc-internal`. 
+-- These were the (rejected) alternative designs back then:
 --
 --  1b. Build the in-tree TH with the stage0 compiler and link the stage1 compiler
 --      against it. This is what we did until Apr 24 and it is problematic (#23536):
@@ -2986,7 +2983,7 @@ tcGetInterp = do
 --           thus rejected.)
 --        * We have thus made it impossible to refactor in-tree TH.
 --          This problem was discussed in #23536.
---  1c. Do not build the stage1 compiler against any template-haskell library.
+--  1c. Do not build the stage1 compiler against any library exposing the in-tree TH AST.
 --      This is viable because no splices need to be run as part of the
 --      bootstrapping process, so we could CPP away all the code in the stage1
 --      compiler that refers to template-haskell types. However,