Document why it is a bad idea to add a formal-receiver->actual-return link when optimizing returned parameters.

Author: cstancu

substratevm/src/com.oracle.graal.pointsto/src/com/oracle/graal/pointsto/flow/InvokeTypeFlow.java

@@ -183,6 +183,10 @@ protected void updateReceiver(PointsToAnalysis bb, MethodFlowsGraphInfo calleeFl
             if (bb.optimizeReturnedParameter()) {
                 int paramIndex = calleeFlows.getMethod().getTypeFlow().getReturnedParameterIndex();
                 if (actualReturn != null && paramIndex == 0) {
+                    /*
+                     * The callee returns `this`. Propagate the receiver state to the actual-return.
+                     * See also InvokeTypeFlow#linkReturn() for more details.
+                     */
                     actualReturn.addState(bb, receiverTypeState);
                 }
             }
@@ -240,10 +244,21 @@ public void linkReturn(PointsToAnalysis bb, boolean isStatic, MethodFlowsGraphIn
                         if (isStatic || paramNodeIndex != 0) {
                             TypeFlow<?> actualParam = actualParameters[paramNodeIndex];
                             actualParam.addUse(bb, actualReturn);
+                        } else {
+                            /*
+                             * The callee returns `this`. The formal-receiver state is updated in
+                             * InvokeTypeFlow#updateReceiver() for each linked callee and every time
+                             * the formal-receiver is updated then the same update state is
+                             * propagated to the actual-return. One may think that we could simply
+                             * add a direct use link from the formal-receiver in the callee to the
+                             * actual-return in the caller to get the state propagation
+                             * automatically. But that would be wrong because then the actual-return
+                             * would get the state from *all* the other places that callee may be
+                             * called from, and that would defeat the purpose of this optimization:
+                             * we want just the receiver state from the caller of current invoke to
+                             * reach the actual-return.
+                             */
                         }
-                        // else {
-                        // receiver object state is transferred in updateReceiver()
-                        // }
                     } else {
                         /*
                          * The callee may have a return type, hence the actualReturn is non-null,