Make sure we don't forget the very important information. It explains why we saw assertions while trying to replace a llvm value, with another.

lib/Interpreter/ASTNodeEraser.cpp

@@ -277,6 +277,30 @@ namespace cling {
 
     // if it was successfully removed from the AST we have to check whether
     // code was generated and remove it.
+
+    // From llvm's mailing list, explanation of the RAUW'd assert:
+    //
+    // The problem isn't with your call to 
+    // replaceAllUsesWith per se, the problem is that somebody (I would guess 
+    // the JIT?) is holding it in a ValueMap.
+    //
+    // We used to have a problem that some parts of the code would keep a 
+    // mapping like so:
+    //    std::map<Value *, ...>
+    // while somebody else would modify the Value* without them noticing, 
+    // leading to a dangling pointer in the map. To fix that, we invented the 
+    // ValueMap which puts a Use that doesn't show up in the use_iterator on 
+    // the Value it holds. When the Value is erased or RAUW'd, the ValueMap is 
+    // notified and in this case decides that's not okay and terminates the 
+    // program.
+    //
+    // Probably what's happened here is that the calling function has had its 
+    // code generated by the JIT, but not the callee. Thus the JIT emitted a 
+    // call to a generated stub, and will do the codegen of the callee once 
+    // that stub is reached. Of course, once the JIT is in this state, it holds 
+    // on to the Function with a ValueMap in order to prevent things from 
+    // getting out of sync.
+    //
     if (Successful && m_CurTransaction->getState() == Transaction::kCommitted) {
       std::string mangledName = ND->getName();