From 9ab5858c0664bd97d86c48248aefd9847b6980c4 Mon Sep 17 00:00:00 2001
From: ghm <ghm@google.com>
Date: Mon, 28 Oct 2024 07:37:51 -0700
Subject: [PATCH] Document our exciting Matches/NotMatches discoveries on
 @Placeholder.

PiperOrigin-RevId: 690605162
---
 .../google/errorprone/refaster/annotation/Placeholder.java    | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/core/src/main/java/com/google/errorprone/refaster/annotation/Placeholder.java b/core/src/main/java/com/google/errorprone/refaster/annotation/Placeholder.java
index 76baaca0039..4350b552842 100644
--- a/core/src/main/java/com/google/errorprone/refaster/annotation/Placeholder.java
+++ b/core/src/main/java/com/google/errorprone/refaster/annotation/Placeholder.java
@@ -79,6 +79,10 @@
  * <em>must</em> contain references to all arguments that <em>are</em> passed to them -- except
  * those corresponding to parameters annotated with {@link MayOptionallyUse}.
  *
+ * <p>Note that {@link Matches} and {@link NotMatches} can be applied to placeholder methods, but,
+ * <strong>and this is a serious health warning</strong>, those predicates will only be matched if
+ * the placeholder method is used as an <em>expression</em>, not a <em>statement</em>.
+ *
  * @author lowasser@google.com (Louis Wasserman)
  */
 @Target(ElementType.METHOD)