From 77bee2d1fbb8e7c1d0b37fa76261176124a26627 Mon Sep 17 00:00:00 2001
From: Kurt Alfred Kluever <kak@google.com>
Date: Fri, 10 Jul 2026 09:18:56 -0700
Subject: [PATCH] Guard requestBlankLine in writeTableOpen, writePreOpen, and
 writeBlockquoteOpenOrClose of JavadocWriter.

* Prevent inserting leading blank lines (`///`) before `<table>`, `<pre>`, and `<blockquote>` when they appear as the very first token in a Javadoc comment by checking `if (wroteAnythingSignificant)` before requesting a blank line.
* Add `tableAtStartOfComment()`, `preAtStartOfComment()`, and `blockquoteAtStartOfComment()` unit tests in `JavadocFormattingTest`.
* Add `tableInHtmlListItem()` and `tableInsideMarkdownListItemAfterText()` unit tests in `JavadocFormattingTest` to document existing list-item table spacing behavior (Thread 4 discussion).

PiperOrigin-RevId: 945745386
---
 .../java/javadoc/JavadocWriter.java           | 12 ++-
 .../java/JavadocFormattingTest.java           | 88 ++++++++++++++++++-
 2 files changed, 96 insertions(+), 4 deletions(-)

diff --git a/core/src/main/java/com/google/googlejavaformat/java/javadoc/JavadocWriter.java b/core/src/main/java/com/google/googlejavaformat/java/javadoc/JavadocWriter.java
index 53f6f1a29..e27f39b3e 100644
--- a/core/src/main/java/com/google/googlejavaformat/java/javadoc/JavadocWriter.java
+++ b/core/src/main/java/com/google/googlejavaformat/java/javadoc/JavadocWriter.java
@@ -260,7 +260,9 @@ void writeParagraphOpen(Token token) {
   }
 
   void writeBlockquoteOpenOrClose(Token token) {
-    requestBlankLine();
+    if (wroteAnythingSignificant) {
+      requestBlankLine();
+    }
 
     writeToken(token);
 
@@ -268,7 +270,9 @@ void writeBlockquoteOpenOrClose(Token token) {
   }
 
   void writePreOpen(PreOpenTag token) {
-    requestBlankLine();
+    if (wroteAnythingSignificant) {
+      requestBlankLine();
+    }
 
     writeToken(token);
   }
@@ -288,7 +292,9 @@ void writeCodeClose(CodeCloseTag token) {
   }
 
   void writeTableOpen(TableOpenTag token) {
-    requestBlankLine();
+    if (wroteAnythingSignificant) {
+      requestBlankLine();
+    }
 
     writeToken(token);
   }
diff --git a/core/src/test/java/com/google/googlejavaformat/java/JavadocFormattingTest.java b/core/src/test/java/com/google/googlejavaformat/java/JavadocFormattingTest.java
index ac4cfc088..7083a878d 100644
--- a/core/src/test/java/com/google/googlejavaformat/java/JavadocFormattingTest.java
+++ b/core/src/test/java/com/google/googlejavaformat/java/JavadocFormattingTest.java
@@ -2160,14 +2160,100 @@ public void tableAtStartOfComment() {
         /// </table>
         class Test {}
         """;
-    // TODO(kak): we shouldn't spew out these 2 leading blank lines
+    String expected = input;
+    doFormatTest(input, expected);
+  }
+
+  @Test
+  public void blockquoteAtStartOfComment() {
+    assume().that(MARKDOWN_JAVADOC_SUPPORTED).isTrue();
+    String input =
+        """
+        /// <blockquote>
+        /// line 1
+        /// line 2
+        /// </blockquote>
+        class Test {}
+        """;
     String expected =
         """
+        /// <blockquote>
         ///
+        /// line 1 line 2
         ///
+        /// </blockquote>
+        class Test {}
+        """;
+    doFormatTest(input, expected);
+  }
+
+  @Test
+  public void preAtStartOfComment() {
+    assume().that(MARKDOWN_JAVADOC_SUPPORTED).isTrue();
+    String input =
+        """
+        /// <pre>
+        /// line 1
+        /// line 2
+        /// </pre>
+        class Test {}
+        """;
+    String expected = input;
+    doFormatTest(input, expected);
+  }
+
+  @Test
+  public void tableInHtmlListItem() {
+    assume().that(MARKDOWN_JAVADOC_SUPPORTED).isTrue();
+    String input =
+        """
+        /// <ul>
+        /// <li>
         /// <table>
         /// <tr><td>Foo</td></tr>
         /// </table>
+        /// </li>
+        /// </ul>
+        class Test {}
+        """;
+    // requestBlankLine() in writeTableOpen() inserts a blank line after <li> before <table> when
+    // inside a list item.
+    String expected =
+        """
+        /// <ul>
+        ///   <li>
+        ///
+        ///       <table>
+        /// <tr><td>Foo</td></tr>
+        /// </table>
+        ///
+        /// </ul>
+        class Test {}
+        """;
+    doFormatTest(input, expected);
+  }
+
+  @Test
+  public void tableInsideMarkdownListItemAfterText() {
+    assume().that(MARKDOWN_JAVADOC_SUPPORTED).isTrue();
+    String input =
+        """
+        /// - item text
+        ///   <table>
+        ///   <tr><td>Foo</td></tr>
+        ///   </table>
+        class Test {}
+        """;
+    // requestBlankLine() in writeTableOpen() inserts a blank line after item text before <table>
+    // inside the list item.
+    String expected =
+        """
+        ///
+        /// - item text
+        ///
+        ///   <table>
+        ///   <tr><td>Foo</td></tr>
+        ///   </table>
         class Test {}
         """;
     doFormatTest(input, expected);