Improve NotJavadoc docs

PiperOrigin-RevId: 538887501
google · Jun 8, 2023 · 03dc338 · 03dc338
1 parent 1e3f53d
commit 03dc338
Show file tree

Hide file tree

Showing 2 changed files with 14 additions and 2 deletions.
diff --git a/core/src/main/java/com/google/errorprone/bugpatterns/javadoc/NotJavadoc.java b/core/src/main/java/com/google/errorprone/bugpatterns/javadoc/NotJavadoc.java
@@ -49,7 +49,7 @@
 
 /** A BugPattern; see the summary. */
 @BugPattern(
-    summary = "Avoid using /** for comments which aren't actually Javadoc.",
+    summary = "Avoid using `/**` for comments which aren't actually Javadoc.",
     severity = WARNING,
     documentSuppression = false)
 public final class NotJavadoc extends BugChecker implements CompilationUnitTreeMatcher {

diff --git a/docs/bugpattern/javadoc/NotJavadoc.md b/docs/bugpattern/javadoc/NotJavadoc.md
@@ -1,6 +1,18 @@
 This comment starts with `/**`, but isn't actually Javadoc.
 
-Consider making it a single-line `//` or a multi-line `/*` comment instead.
+Javadoc comments
+[must precede a class, field, constructor, or method declaration](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#format).
+
+Using `/**` comments in locations where Javadoc is not supported is confusing
+and unnecessary.
+
+Suggested solutions:
+
+*   If the comment is intended to be part of the API documentation, move it to
+    the appropriate class, field, constructor, or method declaration.
+
+*   If the comment is intended to be an implementation comment, use a
+    single-line `//` or a multi-line `/*` comment instead.
 
 ## Suppression