From 7d6f09621f29cd39d650702f3fbf9682ae910b2e Mon Sep 17 00:00:00 2001
From: "copybara-service[bot]" <copybara-service[bot]@users.noreply.github.com>
Date: Mon, 26 Aug 2024 15:59:03 +0000
Subject: [PATCH] Latest docs on successful build 6602 auto-pushed to gh-pages

---
 bugpattern/WithSignatureDiscouraged.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/bugpattern/WithSignatureDiscouraged.md b/bugpattern/WithSignatureDiscouraged.md
index a1902a92c7d..add483daede 100644
--- a/bugpattern/WithSignatureDiscouraged.md
+++ b/bugpattern/WithSignatureDiscouraged.md
@@ -13,6 +13,19 @@ To make changes, edit the @BugPattern annotation or the explanation in docs/bugp
 -->
 
 
+## The problem
+`withSignature` replies on the string representation of internal classes in the
+javac implementation. Those string representations are not necessarily stable
+across versions of javac, and they can change when a method is annotated with
+type-use annotations.
+
+Additionally, `withSignature` currently has at least one undocumented behavioral
+quirk.
+
+The most reasonable use case for `withSignature` is for methods that declare or
+use type variables, which are difficult or impossible to express with the rest
+of the `MethodMatchers` API. Still, where practical, prefer to write your own
+matching code instead of using `withSignature`.
 
 ## Suppression
 Suppress false positives by adding the suppression annotation `@SuppressWarnings("WithSignatureDiscouraged")` to the enclosing element.