Skip to content

Drop the <p> tags that end a Javadoc comment - #247

Open
abashev wants to merge 5 commits into
21.X.Xfrom
abashev/javadoc-drop-an-empty-trailing-p-tag
Open

abashev wants to merge 5 commits into
21.X.Xfrom
abashev/javadoc-drop-an-empty-trailing-p-tag

Conversation

@abashev

@abashev abashev commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #237. Independent of the other open pull requests; based on 21.X.X.

A <p> with nothing after it was written on a line of its own after a blank one, so the formatter kept a dangling paragraph tag, and a comment that would otherwise fit on one line stayed on several. JavadocLexer now ends generateTokens() with removeTrailingParagraphTags, which removes the <p> tags at the end of the comment, with the whitespace and </p> tags among them, before JavadocWriter sees them.

/**
 * The client's first name.
 *
 * <p>
 */
class Test {}

now becomes

/** The client's first name. */
class Test {}

Against the upstream pull request

google-java-format#1526 (open, no review yet) adds the same pass. This one differs in three ways:

  • Every trailing <p> goes, not only the last. With two, removing one left the other for the next run, so formatting was not idempotent.
  • A </p> among them is skipped, so a closing <p></p> goes too. The writer already ignored </p>.
  • A <p> with attributes stays, such as <p id="end">: its id may be the target of a link. Only <p>, <P>, <p/> and <p > are removed.

Upstream runs the pass for classic Javadoc only, to leave Markdown comments alone. No guard is needed here: /// comments are line comments to this formatter and never reach the Javadoc lexer.

What changes for users

Only with Javadoc formatting on, which is off by default. Of the 129,775 Javadoc comments in the 15,747 JDK 21 sources, 9 change, in 9 files, each losing a trailing <p>; three of them become one-liners, such as XToolkit's /** XSETTINGS for the default screen. */. The comments that a second run changes are the same 28 before and after, at 120 columns (32 at 100 columns on both).

Tests

Written first, in JavadocFormattingTest:

  • removeTrailingParagraphTag: the example above.
  • removeEveryTrailingParagraphTag: a <p> after @param, and a closing <p></p> followed by <P/>.
  • keepTrailingParagraphTagWithAttributes: <p id="end"> stays. It passes on 21.X.X too, and pins the exception.

On 21.X.X the first two fail. With the change, ./gradlew check passes on JDK 21.

AlmostJavadoc

A second commit makes Error Prone's AlmostJavadoc an error. Its only two findings showed on this pull request, which changes JavadocLexer, and both were block comments meant as Javadoc: the one above JavadocLexer.LITERAL_PATTERN, which joinAdjacentLiteralsAndAdjacentWhitespace already links to, and the @param of CharStream.tryConsumeRegex. Both are Javadoc now. ./gradlew clean check --no-build-cache passes with the check as an error.

CI: no macOS arm64 native build

The last two commits take the macOS arm64 native image out of CI. GitHub's macOS arm64 runners are scarce: from 17 to 19 November 2026 it found none for 13 of the job's 21 pull-request runs, and each failed after 15 minutes with "The job was not acquired by Runner", this pull request's first run among them. release.yml does not change and still builds that image.

The native job's matrix is now the list of runners, with macos-15 commented out, and each job is named after its runner: native (ubuntu-latest), native (ubuntu-24.04-arm), native (macos-15-intel), native (windows-latest). The platform names only named the jobs. (The third commit left the image out of pull requests only, with an exclude on the event; the fourth replaces that.) mise run ci:native picks its job by the new key, and the README's act caveats use the new names. actionlint passes. Only build is a required check.

A <p> with nothing after it was written on a line of its own after a
blank one, so a comment whose last line was a bare <p> kept it, and
one that would otherwise fit on a line stayed on several. The lexer
now removes the <p> tags at the end of the comment, with the
whitespace and </p> tags among them, before the writer sees them.

google-java-format#1526 proposes the same pass upstream, still
unreviewed. This one differs in three ways:
- Every trailing <p> goes, not only the last: with two, removing one
  left the other for the next run, so formatting was not idempotent.
- A </p> among them is skipped, so a closing "<p></p>" goes too.
- A <p> with attributes stays: its id may be the target of a link.

The tests were written first: removeTrailingParagraphTag and
removeEveryTrailingParagraphTag failed before the change. Of the
129,775 Javadoc comments in the 15,747 JDK 21 sources, 9 change, each
losing a trailing <p>; the comments that a second run changes are the
same 28 as before, at 120 columns.

Closes #237
Its two findings were block comments meant as Javadoc, both in the
javadoc package:
- The comment above JavadocLexer.LITERAL_PATTERN, which the Javadoc of
  joinAdjacentLiteralsAndAdjacentWhitespace links to for the
  discussion, is the field's Javadoc now: its HTML samples are in
  {@code}, and the method it names is a link.
- CharStream.tryConsumeRegex's @PARAM is in a Javadoc, with a summary.
GitHub's macOS arm64 runners are scarce. From 17 to 19 November 2026
it found none for 13 of the job's 21 pull-request runs: each waited
15 minutes and failed with "The job was not acquired by Runner of type
hosted even after multiple attempts". Pull requests now build the
other four platforms; pushes to a release line still build all five,
and the release workflow does not change.

The matrix lists the platforms and excludes macos-aarch64 when the
event is a pull request. The runners moved from the matrix's include
to a table in runs-on: an include entry that matches no combination
adds one, so it would have put the excluded platform back.

Only build is a required check, so no pull request waited for the job.
The platform names in the native job's matrix only named the jobs.
The matrix is now the list of runners, and each job is named after
its own: native (ubuntu-latest), native (macos-15-intel) and so on.
Nothing requires those checks.

macos-15 is commented out, for pushes too, instead of left out of pull
requests only, which took an exclude on the event and a table of
runners in runs-on. The release workflow still builds the macOS arm64
image.

mise's ci:native task picks its job by the new key, and the README's
act caveats use the new names.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Javadoc: drop an empty trailing <p> tag

1 participant