Repository navigation
Conversation
Lines inside a `<pre>{@code ...}` block that omit the `*` margin lost all
their leading whitespace, because the lexer's newline pattern ate the
indentation of every continuation line. Code samples written this way (the
JDK's java.lang.invoke docs, for one) came out flush left.
The lexer now strips the margins line by line before tokenizing, as upstream
does in JavadocFormatter.classicCommentText: the `*` prefix and the space
after it from lines that have one, and the comment's own indentation from
lines that do not. That indentation is the smaller of the shortest `*` prefix
and the shortest bare-line indentation, so a bare line is never cut into and
both kinds of line stay aligned with each other. What remains is relative to
the comment, which is what deindentPreCodeBlocks expects. The newline pattern
shrinks to the trailing whitespace and the newline itself.
HTML comments were the one construct that still saw the raw margins, so the
writer now puts the margin back on each of their lines, as upstream's does;
commentMostlyUntouched takes upstream's current expectation (`* abc`,
`* def`, `* -->`) instead of the raw `*abc`.
Resolves the same defect as google/google-java-format#1476, whose patch does
not apply here (no classicCommentText in this fork). Tests first:
preCodeWithoutLeadingStarPreservesIndent (upstream's case),
preCodeWithoutLeadingStarInIndentedComment (comment indented by four, the
base column must go) and preCodeMixedStarAndBareLinesKeepRelativeIndent all
failed with the sample flush left.
java.base of JDK 21 with Javadoc formatting on: 6 of 3,474 files change, all
of them bare-line code samples regaining their indentation.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The defect of google/google-java-format#1476, fixed in this fork's own way: upstream's patch edits
JavadocFormatter.classicCommentText, which does not exist here, so the change lives in the lexer.Problem. With Javadoc formatting on, lines inside
<pre>{@code ...}that omit the*margin lost all their leading whitespace, becauseNEWLINE_PATTERNate the indentation of every continuation line. The JDK'sjava.lang.invokedocs are written this way and came out flush left.Fix.
JavadocLexer.stripMarginsremoves the margins line by line before tokenizing, mirroring upstream'sclassicCommentText: the*prefix plus one space from lines that have it, and the comment's own indentation from lines that do not. That indentation ismin(shortest * prefix, shortest bare-line indentation), so a bare line is never cut into and both kinds of line stay aligned. What is left is relative to the comment, which is whatdeindentPreCodeBlocksalready expects.NEWLINE_PATTERNshrinks to^[ \t]*\n, the same as upstream's.HTML comments were the one construct that still saw raw margins (the whole
<!-- ... -->is one token). The writer now re-adds the margin to each of their lines, as upstream'swriteHtmlCommentdoes, andcommentMostlyUntouchedtakes upstream's current expectation:* abc,* def,* -->instead of the raw*abc. That is the one visible behaviour change outside bare-line code samples; say if the raw form should be kept instead.Tests first.
preCodeWithoutLeadingStarPreservesIndent(upstream's case),preCodeWithoutLeadingStarInIndentedComment(comment indented by four, so the base column really has to go) andpreCodeMixedStarAndBareLinesKeepRelativeIndentall failed with the sample flush left. The first and third carry a summary line before<pre>, so they do not depend on the leading-blank-lines fix in #116. Full module suite: 1612 tests, 0 failures.Blast radius. java.base of JDK 21, 3,474 files, formatted with
formatJavadoc(true)by main's jar and this branch's jar: 6 files differ (BootstrapCallInfo,CallSite,MethodHandle,MethodHandles,MutableCallSite,Cleaner), every hunk a bare-line code sample regaining its indentation. The other 3,468 are byte-identical, so the rewritten margin handling changes nothing for*lines.Only reachable through
JavaFormatterOptions.formatJavadoc(true); the CLI and plugins are unaffected.