Update the "evaluatesToLocalValue" to explain what is intended to be used for.
@@ -4603,8 +4603,8 @@ public final class NodeUtil {
}
/**
- * @return Whether the node is known to be a value that is not referenced
- * elsewhere.
+ * @return Whether the result of the expression node is known to be a primitive value
+ * or an object that has not yet escaped.
*/
static boolean evaluatesToLocalValue(Node value) {
return evaluatesToLocalValue(value, Predicates.<Node>alwaysFalse());
@@ -4612,8 +4612,21 @@ public final class NodeUtil {
/**
* @param locals A predicate to apply to unknown local values.
- * @return Whether the node is known to be a value that is not a reference
- * outside the expression scope.
+ * @return Whether the result of the expression node is known to be a primitive value
+ * or an object that has not yet escaped. This guarantee is different
+ * than that provided by isLiteralValue (where literal values are immune to side-effects
+ * if unescaped) or isImmutableValue (which can be safely aliased).
+ *
+ * The concept of "local values" allow for the containment of side-effect operations. For
+ * example, a setting a property on a local value does not produce a global side-effect.
+ *
+ * Note that the concept of "local value" is not deep, it does not say anything
+ * about the properties of the "local value" (all class instances have "constructor" properties
+ * that are not local values for instance).
+ *
+ * Note that this method only provides the starting state of the expression result,
+ * it does not guarantee that the value is forever a local value. If the containing
+ * method has any non-local side-effect, "local values" may escape.
*/
static boolean evaluatesToLocalValue(Node value, Predicate<Node> locals) {
switch (value.getToken()) {
