Merge pull request #27999 from compnerd/documentation

Basic: add a comment about the "complex" code

Author: compnerd

include/swift/Basic/Mangler.h

@@ -124,6 +124,11 @@ class Mangler {
   /// Appends a mangled identifier string.
   void appendIdentifier(StringRef ident);
 
+  // NOTE: the addSubsitution functions perform the value computation before
+  // the assignment because there is no sequence point synchronising the
+  // computation of the value before the insertion of the new key, resulting in
+  // the computed value being off-by-one causing an undecoration failure during
+  // round-tripping.
   void addSubstitution(const void *ptr) {
     if (!UseSubstitutions)
       return;