Initial support for Markdown Javadoc.

This is work in progress and *may mangle some Markdown Javadoc comments*. Later changes will address that.

Currently supported Markdown constructs: newline-separated paragraphs; `# Headings`; and `- Bullet lists`. `*Emphasis*` and `**Strong emphasis**` should work too because they don't need any special treatment. Other constructs probably don't work, notably code blocks.

PiperOrigin-RevId: 892607809

Author: eamonnmcmanus

core/pom.xml

@@ -39,6 +39,11 @@
       <groupId>com.google.guava</groupId>
       <artifactId>guava</artifactId>
     </dependency>
+    <dependency>
+      <groupId>org.commonmark</groupId>
+      <artifactId>commonmark</artifactId>
+      <version>0.28.0</version>
+    </dependency>
 
     <!-- Compile-time dependencies -->
     <dependency>

core/src/main/java/com/google/googlejavaformat/java/JavaCommentsHelper.java

@@ -50,7 +50,13 @@ public String rewrite(Tok tok, int maxWidth, int column0) {
     }
     String text = tok.getOriginalText();
     if (tok.isJavadocComment() && options.formatJavadoc()) {
-      text = JavadocFormatter.formatJavadoc(text, column0);
+      if (text.startsWith("///")) {
+        if (markdownJavadocPositions.contains(tok.getPosition())) {
+          return JavadocFormatter.formatJavadoc(text, column0);
+        }
+      } else {
+        text = JavadocFormatter.formatJavadoc(text, column0);
+      }
     }
     List<String> lines = new ArrayList<>();
     Iterator<String> it = Newlines.lineIterator(text);

core/src/main/java/com/google/googlejavaformat/java/JavaInput.java

@@ -160,9 +160,13 @@ public boolean isSlashStarComment() {
 
     @Override
     public boolean isJavadocComment() {
-      // 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;
+      // comments like `/***` or `////` are also javadoc, but their formatting probably won't be
+      // improved by the javadoc formatter
+      return ((text.startsWith("/**") && !text.startsWith("/***"))
+              || (Runtime.version().feature() >= 23
+                  && text.startsWith("///")
+                  && !text.startsWith("////")))
+          && text.length() > 4;
     }
 
     @Override

core/src/main/java/com/google/googlejavaformat/java/javadoc/CharStream.java

@@ -27,18 +27,18 @@
  */
 final class CharStream {
   private final String input;
-  private int start;
+  private int position;
   private int tokenEnd = -1; // Negative value means no token, and will cause an exception if used.
 
   CharStream(String input) {
     this.input = checkNotNull(input);
   }
 
   boolean tryConsume(String expected) {
-    if (!input.startsWith(expected, start)) {
+    if (!input.startsWith(expected, position)) {
       return false;
     }
-    tokenEnd = start + expected.length();
+    tokenEnd = position + expected.length();
     return true;
   }
 
@@ -48,7 +48,7 @@ boolean tryConsume(String expected) {
    * @param pattern the pattern to search for, which must be anchored to match only at position 0
    */
   boolean tryConsumeRegex(Pattern pattern) {
-    Matcher matcher = pattern.matcher(input).region(start, input.length());
+    Matcher matcher = pattern.matcher(input).region(position, input.length());
     if (!matcher.lookingAt()) {
       return false;
     }
@@ -57,13 +57,17 @@ boolean tryConsumeRegex(Pattern pattern) {
   }
 
   String readAndResetRecorded() {
-    String result = input.substring(start, tokenEnd);
-    start = tokenEnd;
+    String result = input.substring(position, tokenEnd);
+    position = tokenEnd;
     tokenEnd = -1;
     return result;
   }
 
   boolean isExhausted() {
-    return start == input.length();
+    return position == input.length();
+  }
+
+  int position() {
+    return position;
   }
 }

core/src/main/java/com/google/googlejavaformat/java/javadoc/JavadocFormatter.java

@@ -14,12 +14,15 @@
 
 package com.google.googlejavaformat.java.javadoc;
 
+import static com.google.common.base.Preconditions.checkState;
 import static com.google.googlejavaformat.java.javadoc.JavadocLexer.lex;
 import static com.google.googlejavaformat.java.javadoc.Token.Type.BR_TAG;
 import static com.google.googlejavaformat.java.javadoc.Token.Type.PARAGRAPH_OPEN_TAG;
 import static java.util.regex.Pattern.CASE_INSENSITIVE;
 import static java.util.regex.Pattern.compile;
+import static java.util.stream.Collectors.joining;
 
+import com.google.common.base.CharMatcher;
 import com.google.common.collect.ImmutableList;
 import com.google.googlejavaformat.java.javadoc.JavadocLexer.LexException;
 import java.util.List;
@@ -39,22 +42,37 @@ public final class JavadocFormatter {
   static final int MAX_LINE_LENGTH = 100;
 
   /**
-   * Formats the given Javadoc comment, which must start with ∕✱✱ and end with ✱∕. The output will
-   * start and end with the same characters.
+   * Formats the given Javadoc comment. A classic Javadoc comment must start with ∕✱✱ and end with
+   * ✱∕, and the output will start and end with the same characters. A Markdown Javadoc comment
+   * consists of lines each of which starts with ///, and the output will also consist of such
+   * lines.
    */
   public static String formatJavadoc(String input, int blockIndent) {
+    boolean classicJavadoc =
+        switch (input) {
+          case String s when s.startsWith("/**") -> true;
+          case String s when s.startsWith("///") -> false;
+          default ->
+              throw new IllegalArgumentException("Input does not start with /** or ///: " + input);
+        };
+    if (!classicJavadoc) {
+      input = "/// " + markdownCommentText(input);
+    }
     ImmutableList<Token> tokens;
     try {
-      tokens = lex(input);
+      tokens = lex(input, classicJavadoc);
     } catch (LexException e) {
       return input;
     }
-    String result = render(tokens, blockIndent);
-    return makeSingleLineIfPossible(blockIndent, result);
+    String result = render(tokens, blockIndent, classicJavadoc);
+    if (classicJavadoc) {
+      result = makeSingleLineIfPossible(blockIndent, result);
+    }
+    return result;
   }
 
-  private static String render(List<Token> input, int blockIndent) {
-    JavadocWriter output = new JavadocWriter(blockIndent);
+  private static String render(List<Token> input, int blockIndent, boolean classicJavadoc) {
+    JavadocWriter output = new JavadocWriter(blockIndent, classicJavadoc);
     for (Token token : input) {
       switch (token.type()) {
         case BEGIN_JAVADOC -> output.writeBeginJavadoc();
@@ -144,5 +162,29 @@ private static boolean oneLineJavadoc(String line, int blockIndent) {
     return true;
   }
 
+  private static final CharMatcher NOT_SPACE_OR_TAB = CharMatcher.noneOf(" \t");
+
+  /**
+   * Returns the given string with the leading /// and any common leading whitespace removed from
+   * each line. The resultant string can then be fed to a standard Markdown parser.
+   */
+  private static String markdownCommentText(String input) {
+    List<String> lines =
+        input
+            .lines()
+            .peek(line -> checkState(line.contains("///"), "Line does not contain ///: %s", line))
+            .map(line -> line.substring(line.indexOf("///") + 3))
+            .toList();
+    int leadingSpace =
+        lines.stream()
+            .filter(line -> NOT_SPACE_OR_TAB.matchesAnyOf(line))
+            .mapToInt(NOT_SPACE_OR_TAB::indexIn)
+            .min()
+            .orElse(0);
+    return lines.stream()
+        .map(line -> line.length() < leadingSpace ? "" : line.substring(leadingSpace))
+        .collect(joining("\n"));
+  }
+
   private JavadocFormatter() {}
 }