From efab3649b685d92b1856a62532b343ef70777612 Mon Sep 17 00:00:00 2001
From: brandon s allbery kf8nh <allbery.b@gmail.com>
Date: Sun, 31 Mar 2024 15:02:06 -0400
Subject: [PATCH] clarify Note [Preproccesing invocations]

---
 compiler/GHC/SysTools/Cpp.hs | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/compiler/GHC/SysTools/Cpp.hs b/compiler/GHC/SysTools/Cpp.hs
index 762756369657..fd7688492b9b 100644
--- a/compiler/GHC/SysTools/Cpp.hs
+++ b/compiler/GHC/SysTools/Cpp.hs
@@ -63,7 +63,22 @@ underlying program (the C compiler), the set of flags passed determines the
 behaviour of the preprocessor, and Cpp and HsCpp behave differently.
 Specifically, we rely on "traditional" (pre-standard) preprocessing semantics
 (which most compilers expose via the `-traditional` flag) when preprocessing
-Haskell source. This avoids, e.g., the preprocessor removing C-style comments.
+Haskell source. This avoids the following situations:
+
+  * Removal of C-style comments, which are not comments in Haskell but valid
+    operators;
+
+  * Errors due to an ANSI C preprocessor lexing the source and failing on
+    names with single quotes (TH quotes, ticked promoted constructors,
+    names with primes in them).
+
+  Both of those cases may be subtle: gcc and clang permit C++-style //
+  comments in C code, and Data.Array and Data.Vector both export a //
+  operator whose type is such that a removed "comment" may leave code that
+  typechecks but does the wrong thing. Another example is that, since ANSI
+  C permits long character constants, an expression involving multiple
+  functions with primes in their names may not expand macros properly when
+  they occur between the primed functions.
 -}
 
 -- | Run either the Haskell preprocessor or the C preprocessor, as per the
-- 
GitLab