Avoid mangling {@snippet ...}.

This CL also implements some minimal formatting behavior _around_ `{@snippet ...}` (namely, a blank line before and after). It does not make any effort to change formatting _inside_ `{@snippet ...}`, only to stop reflowing it blindly. PiperOrigin-RevId: 665555661

Author: cpovirk

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

@@ -66,6 +66,12 @@ private static String render(List<Token> input, int blockIndent) {
  case FOOTER_JAVADOC_TAG_START:
  output.writeFooterJavadocTagStart(token);
  break;
+ case SNIPPET_BEGIN:
+ output.writeSnippetBegin(token);
+ break;
+ case SNIPPET_END:
+ output.writeSnippetEnd(token);
+ break;
  case LIST_OPEN_TAG:
  output.writeListOpen(token);
  break;

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

@@ -42,6 +42,8 @@
 import static com.google.googlejavaformat.java.javadoc.Token.Type.PARAGRAPH_OPEN_TAG;
 import static com.google.googlejavaformat.java.javadoc.Token.Type.PRE_CLOSE_TAG;
 import static com.google.googlejavaformat.java.javadoc.Token.Type.PRE_OPEN_TAG;
+import static com.google.googlejavaformat.java.javadoc.Token.Type.SNIPPET_BEGIN;
+import static com.google.googlejavaformat.java.javadoc.Token.Type.SNIPPET_END;
 import static com.google.googlejavaformat.java.javadoc.Token.Type.TABLE_CLOSE_TAG;
 import static com.google.googlejavaformat.java.javadoc.Token.Type.TABLE_OPEN_TAG;
 import static com.google.googlejavaformat.java.javadoc.Token.Type.WHITESPACE;
@@ -97,6 +99,7 @@ private static String stripJavadocBeginAndEnd(String input) {
  private final NestingCounter preDepth = new NestingCounter();
  private final NestingCounter codeDepth = new NestingCounter();
  private final NestingCounter tableDepth = new NestingCounter();
+ private boolean outerInlineTagIsSnippet;
  private boolean somethingSinceNewline;
 
  private JavadocLexer(CharStream input) {
@@ -158,13 +161,26 @@ private Type consumeToken() throws LexException {
  }
  somethingSinceNewline = true;
 
- if (input.tryConsumeRegex(INLINE_TAG_OPEN_PATTERN)) {
+ if (input.tryConsumeRegex(SNIPPET_TAG_OPEN_PATTERN)) {
+ if (braceDepth.value() == 0) {
+ braceDepth.increment();
+ outerInlineTagIsSnippet = true;
+ return SNIPPET_BEGIN;
+ }
+ braceDepth.increment();
+ return LITERAL;
+ } else if (input.tryConsumeRegex(INLINE_TAG_OPEN_PATTERN)) {
  braceDepth.increment();
  return LITERAL;
  } else if (input.tryConsume("{")) {
  braceDepth.incrementIfPositive();
  return LITERAL;
  } else if (input.tryConsume("}")) {
+ if (outerInlineTagIsSnippet && braceDepth.value() == 1) {
+ braceDepth.decrementIfPositive();
+ outerInlineTagIsSnippet = false;
+ return SNIPPET_END;
+ }
  braceDepth.decrementIfPositive();
  return LITERAL;
  }
@@ -239,7 +255,10 @@ private Type consumeToken() throws LexException {
  }
 
  private boolean preserveExistingFormatting() {
- return preDepth.isPositive() || tableDepth.isPositive() || codeDepth.isPositive();
+ return preDepth.isPositive()
+ || tableDepth.isPositive()
+ || codeDepth.isPositive()
+ || outerInlineTagIsSnippet;
  }
 
  private void checkMatchingTags() throws LexException {
@@ -400,6 +419,7 @@ private static ImmutableList<Token> optionalizeSpacesAfterLinks(List<Token> inpu
  * <p>Also trim leading and trailing blank lines, and move the trailing `}` to its own line.
  */
  private static ImmutableList<Token> deindentPreCodeBlocks(List<Token> input) {
+ // TODO: b/323389829 - De-indent {@snippet ...} blocks, too.
  ImmutableList.Builder<Token> output = ImmutableList.builder();
  for (PeekingIterator<Token> tokens = peekingIterator(input.iterator()); tokens.hasNext(); ) {
  if (tokens.peek().getType() != PRE_OPEN_TAG) {
@@ -528,6 +548,7 @@ private static boolean hasMultipleNewlines(String s) {
  private static final Pattern BLOCKQUOTE_OPEN_PATTERN = openTagPattern("blockquote");
  private static final Pattern BLOCKQUOTE_CLOSE_PATTERN = closeTagPattern("blockquote");
  private static final Pattern BR_PATTERN = openTagPattern("br");
+ private static final Pattern SNIPPET_TAG_OPEN_PATTERN = compile("^[{]@snippet\\b");
  private static final Pattern INLINE_TAG_OPEN_PATTERN = compile("^[{]@\\w*");
  /*
  * We exclude < so that we don't swallow following HTML tags. This lets us fix up "foo<p>" (~400

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

@@ -123,6 +123,38 @@ void writeFooterJavadocTagStart(Token token) {
  continuingFooterTag = true;
  }
 
+ void writeSnippetBegin(Token token) {
+ requestBlankLine();
+ writeToken(token);
+ /*
+ * We don't request a newline here because we should have at least a colon following on this
+ * line, and we may have attributes after that.
+ *
+ * (If we find it convenient, we could instead consume the entire rest of the line as part of
+ * the same token as `{@snippet` itself. But we already would never split the rest of the line
+ * across lines (because we preserve whitespace), so that might not accomplish anything. Plus,
+ * we'd probably want to be careful not to swallow an expectedly early closing `}`.)
+ */
+ }
+
+ void writeSnippetEnd(Token token) {
+ /*
+ * We don't request a newline here because we have preserved all newlines that existed in the
+ * input. TODO: b/323389829 - Improve upon that. Specifically:
+ *
+ * - If there is not yet a newline, we should add one.
+ *
+ * - If there are multiple newlines, we should probably collapse them.
+ *
+ * - If the closing brace isn't indented as we'd want (as in the link below, in which the whole
+ * @apiNote isn't indented), we should indent it.
+ *
+ * https://github.com/openjdk/jdk/blob/1ebf2cf639300728ffc024784f5dc1704317b0b3/src/java.base/share/classes/java/util/Collections.java#L5993-L6006
+ */
+ writeToken(token);
+ requestBlankLine();
+ }
+
  void writeListOpen(Token token) {
  requestBlankLine();
 

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

@@ -41,6 +41,10 @@ enum Type {
  END_JAVADOC,
  /** The {@code @foo} that begins a block Javadoc tag like {@code @throws}. */
  FOOTER_JAVADOC_TAG_START,
+ /** The opening {@code ｛@snippet} of a code snippet. */
+ SNIPPET_BEGIN,
+ /** The closing {@code ｝} of a code snippet. */
+ SNIPPET_END,
  LIST_OPEN_TAG,
  LIST_CLOSE_TAG,
  LIST_ITEM_OPEN_TAG,

core/src/test/java/com/google/googlejavaformat/java/JavadocFormattingTest.java

@@ -906,6 +906,48 @@ public void unicodeCharacterCountArguableBug() {
  doFormatTest(input, expected);
  }
 
+ @Test
+ public void blankLinesAroundSnippetAndNoMangling() {
+ String[] input = {
+ "/**", //
+ " * hello world",
+ " * {@snippet :",
+ " * public class Foo {",
+ " * private String s;",
+ " * }",
+ " * }",
+ " * hello again",
+ " */",
+ "class Test {}",
+ };
+ String[] expected = {
+ "/**", //
+ " * hello world",
+ " *",
+ " * {@snippet :",
+ " * public class Foo {",
+ " * private String s;",
+ " * }",
+ " * }",
+ " *",
+ " * hello again",
+ " */",
+ "class Test {}",
+ };
+ doFormatTest(input, expected);
+ }
+
+ @Test
+ public void notASnippetUnlessOuterTag() {
+ String[] input = {
+ "/** I would like to tell you about the {@code {@snippet ...}} tag. */", "class Test {}",
+ };
+ String[] expected = {
+ "/** I would like to tell you about the {@code {@snippet ...}} tag. */", "class Test {}",
+ };
+ doFormatTest(input, expected);
+ }
+
  @Test
  public void blankLineBeforeParams() {
  String[] input = {