From 21c190a6fc76f3ad3c895639dc66b7a3f570c55d Mon Sep 17 00:00:00 2001
From: Liam Miller-Cushon <cushon@google.com>
Date: Mon, 18 Dec 2023 07:40:12 -0800
Subject: [PATCH] Document that javadoc shouldn't appear between annotations
 and the documented element

PiperOrigin-RevId: 591893421
---
 docs/bugpattern/javadoc/NotJavadoc.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/bugpattern/javadoc/NotJavadoc.md b/docs/bugpattern/javadoc/NotJavadoc.md
index 6800fc55395..13a7c6d1282 100644
--- a/docs/bugpattern/javadoc/NotJavadoc.md
+++ b/docs/bugpattern/javadoc/NotJavadoc.md
@@ -14,6 +14,23 @@ Suggested solutions:
 *   If the comment is intended to be an implementation comment, use a
     single-line `//` or a multi-line `/*` comment instead.
 
+> NOTE: Javadoc must appear before any annotations, or the compiler will fail to
+> recognise it as Javadoc. That is, prefer this:
+>
+> ```java
+> /** Might return a frobnicator. */
+> @Nullable
+> Frobnicator getFrobnicator();
+> ```
+>
+> instead of this:
+>
+> ```java
+> @Nullable
+> /** Might return a frobnicator. */
+> Frobnicator getFrobnicator();
+> ```
+
 ## Suppression
 
 Suppress by applying `@SuppressWarnings("NotJavadoc")` to the enclosing element.