From 49ff83d6c6a5079ac79bfbb63fe2b9aa005a084d Mon Sep 17 00:00:00 2001
From: cushon <cushon@google.com>
Date: Thu, 24 Sep 2026 23:15:08 +0300
Subject: [PATCH] Leave a comment that opens with "/***" out of javadoc
 formatting

With javadoc formatting on, a banner such as

    /*************************
     * Copyright
     *
     * Some Company
     *************************/

was taken for javadoc because it starts with "/**": the row of
asterisks moved onto a line of its own, and its paragraphs became <p>
tags. The javadoc formatter has nothing to improve in a comment like
that.

This ports upstream commit 37171795 by cushon (google-java-format
1.8): a comment whose fourth character is another asterisk is not
javadoc. That holds with javadoc formatting off as well, where it
decides how blank lines around the comment are treated: a blank line
between such a banner and the declaration after it is now kept, as
after any other block comment, instead of being removed as it would be
after javadoc. The empty() expectation changes accordingly, and a test
pins the banner.

Of the 15,747 files of the JDK 21 sources, 43 format differently, by
70 blank lines more in all and no other change; every one of them is
in the input, after a banner comment. The four of those files that
change again on a second run did so on main already.
---
 .../palantir/javaformat/java/JavaInput.java   |  4 +++-
 .../java/JavadocFormattingTest.java           | 19 ++++++++++++++++++-
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/open-java-format/src/main/java/com/palantir/javaformat/java/JavaInput.java b/open-java-format/src/main/java/com/palantir/javaformat/java/JavaInput.java
index efd1caaff..87fbf5285 100644
--- a/open-java-format/src/main/java/com/palantir/javaformat/java/JavaInput.java
+++ b/open-java-format/src/main/java/com/palantir/javaformat/java/JavaInput.java
@@ -154,7 +154,9 @@ public boolean isSlashStarComment() {
 
         @Override
         public boolean isJavadocComment() {
-            return text.startsWith("/**") && text.length() > 4;
+            // comments like `/***` are also javadoc, but their formatting probably won't be improved
+            // by the javadoc formatter
+            return text.startsWith("/**") && text.charAt("/**".length()) != '*' && text.length() > 4;
         }
 
         @Override
diff --git a/open-java-format/src/test/java/com/palantir/javaformat/java/JavadocFormattingTest.java b/open-java-format/src/test/java/com/palantir/javaformat/java/JavadocFormattingTest.java
index 95f634808..8466debfa 100644
--- a/open-java-format/src/test/java/com/palantir/javaformat/java/JavadocFormattingTest.java
+++ b/open-java-format/src/test/java/com/palantir/javaformat/java/JavadocFormattingTest.java
@@ -55,11 +55,28 @@ public void empty() {
             "class Test {}",
         };
         String[] expected = {
-            "/** */", "class Test {}",
+            "/***/", "class Test {}",
         };
         doFormatTest(input, expected);
     }
 
+    @Test
+    public void bannerCommentIsNotJavadoc() {
+        // A comment that opens with three or more asterisks is left to the plain comment handling: reflowing it as
+        // javadoc would push the asterisks onto a line of their own and turn its paragraphs into <p> tags.
+        String[] input = {
+            "/****************************************",
+            " * Copyright",
+            " *",
+            " * Some",
+            " *",
+            " * Company",
+            " ****************************************/",
+            "class Test {}",
+        };
+        doFormatTest(input, input);
+    }
+
     @Test
     public void emptyMultipleLines() {
         String[] input = {