Add a 'unbounded method refs only' clause to PooledLambda javadoc
Test: proofread
Change-Id: I26f1ac6e61289769a75a629b7b2057d32237a560
diff --git a/core/java/com/android/internal/util/function/pooled/PooledLambda.java b/core/java/com/android/internal/util/function/pooled/PooledLambda.java
index 17b140d..87c25e9 100755
--- a/core/java/com/android/internal/util/function/pooled/PooledLambda.java
+++ b/core/java/com/android/internal/util/function/pooled/PooledLambda.java
@@ -59,6 +59,21 @@
* You can fill the 'missing argument' spot with {@link #__()}
* (which is the factory function for {@link ArgumentPlaceholder})
*
+ * NOTE: It is highly recommended to <b>only</b> use {@code ClassName::methodName}
+ * (aka unbounded method references) as the 1st argument for any of the
+ * factories ({@code obtain*(...)}) to avoid unwanted allocations.
+ * This means <b>not</b> using:
+ * <ul>
+ * <li>{@code someVar::methodName} or {@code this::methodName} as it captures the reference
+ * on the left of {@code ::}, resulting in an allocation on each evaluation of such
+ * bounded method references</li>
+ *
+ * <li>A lambda expression, e.g. {@code () -> toString()} due to how easy it is to accidentally
+ * capture state from outside. In the above lambda expression for example, no variable from
+ * outer scope is explicitly mentioned, yet one is still captured due to {@code toString()}
+ * being an equivalent of {@code this.toString()}</li>
+ * </ul>
+ *
* @hide
*/
@SuppressWarnings({"unchecked", "unused", "WeakerAccess"})