Basic: add a comment about the "complex" code

This addresses comments from Joe to document the special behaviour that
we do in the `addSubsitution` functions which cause a subtle failure on
Windows.

Author: compnerd

include/swift/Basic/Mangler.h

@@ -123,6 +123,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;