From 8fc19b9e1291017b89148a3747fa77efdaf040e2 Mon Sep 17 00:00:00 2001
From: ringabout <43030857+ringabout@users.noreply.github.com>
Date: Mon, 22 Aug 2022 16:11:43 +0800
Subject: [PATCH] document compiler procs regarding `&` (#20257)

---
 compiler/ccgexprs.nim | 4 ++--
 compiler/hlo.nim      | 1 +
 compiler/transf.nim   | 5 +++++
 3 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/compiler/ccgexprs.nim b/compiler/ccgexprs.nim
index 1f16f458f7..1d5ceb779c 100644
--- a/compiler/ccgexprs.nim
+++ b/compiler/ccgexprs.nim
@@ -1197,7 +1197,7 @@ proc strLoc(p: BProc; d: TLoc): Rope =
 
 proc genStrConcat(p: BProc, e: PNode, d: var TLoc) =
   #   <Nim code>
-  #   s = 'Hello ' & name & ', how do you feel?' & 'z'
+  #   s = "Hello " & name & ", how do you feel?" & 'z'
   #
   #   <generated C code>
   #  {
@@ -1240,7 +1240,7 @@ proc genStrConcat(p: BProc, e: PNode, d: var TLoc) =
 
 proc genStrAppend(p: BProc, e: PNode, d: var TLoc) =
   #  <Nim code>
-  #  s &= 'Hello ' & name & ', how do you feel?' & 'z'
+  #  s &= "Hello " & name & ", how do you feel?" & 'z'
   #  // BUG: what if s is on the left side too?
   #  <generated C code>
   #  {
diff --git a/compiler/hlo.nim b/compiler/hlo.nim
index 8620c4c4d1..e3670312e0 100644
--- a/compiler/hlo.nim
+++ b/compiler/hlo.nim
@@ -8,6 +8,7 @@
 #
 
 # This include implements the high level optimization pass.
+# included from sem.nim
 
 when defined(nimPreviewSlimSystem):
   import std/assertions
diff --git a/compiler/transf.nim b/compiler/transf.nim
index bdd7c680cc..47d7fb3a56 100644
--- a/compiler/transf.nim
+++ b/compiler/transf.nim
@@ -806,6 +806,8 @@ proc getMergeOp(n: PNode): PSym =
   else: discard
 
 proc flattenTreeAux(d, a: PNode, op: PSym) =
+  ## Optimizes away the `&` calls in the children nodes and
+  ## lifts the leaf nodes to the same level as `op2`.
   let op2 = getMergeOp(a)
   if op2 != nil and
       (op2.id == op.id or op.magic != mNone and op2.magic == op.magic):
@@ -898,6 +900,9 @@ proc transformExceptBranch(c: PTransf, n: PNode): PNode =
     result = transformSons(c, n)
 
 proc commonOptimizations*(g: ModuleGraph; idgen: IdGenerator; c: PSym, n: PNode): PNode =
+  ## Merges adjacent constant expressions of the children of the `&` call into
+  ## a single constant expression. It also inlines constant expressions which are not
+  ## complex.
   result = n
   for i in 0..<n.safeLen:
     result[i] = commonOptimizations(g, idgen, c, n[i])