From 0030c9697d236dcb87272e7800d9324f738bf23d Mon Sep 17 00:00:00 2001 From: Alex Abashev Date: Thu, 19 Nov 2026 14:03:31 +0300 Subject: [PATCH 1/4] Drop the

tags that end a Javadoc comment A

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

kept it, and one that would otherwise fit on a line stayed on several. The lexer now removes the

tags at the end of the comment, with the whitespace and

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

goes, not only the last: with two, removing one left the other for the next run, so formatting was not idempotent. - A

among them is skipped, so a closing "

" goes too. - A

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

; the comments that a second run changes are the same 28 as before, at 120 columns. Closes #237 --- .../javaformat/java/javadoc/JavadocLexer.java | 32 ++++++++- .../java/JavadocFormattingTest.java | 67 +++++++++++++++++++ 2 files changed, 98 insertions(+), 1 deletion(-) diff --git a/open-java-format/src/main/java/com/palantir/javaformat/java/javadoc/JavadocLexer.java b/open-java-format/src/main/java/com/palantir/javaformat/java/javadoc/JavadocLexer.java index f7fcfe2e7..29637a347 100644 --- a/open-java-format/src/main/java/com/palantir/javaformat/java/javadoc/JavadocLexer.java +++ b/open-java-format/src/main/java/com/palantir/javaformat/java/javadoc/JavadocLexer.java @@ -173,7 +173,8 @@ private List generateTokens() throws LexException { result = joinAdjacentLiteralsAndAdjacentWhitespace(result); result = inferParagraphTags(result); result = optionalizeSpacesAfterLinks(result); - return deindentPreCodeBlocks(result); + result = deindentPreCodeBlocks(result); + return removeTrailingParagraphTags(result); } private Token readToken() throws LexException { @@ -574,6 +575,35 @@ private static void deindentPreCodeBlock(List output, PeekingIterator} tags at the end of the comment, and the whitespace and {@code

} tags among them. + * Nothing follows such a tag, but the writer would still put it on a line of its own after a blank one. + * + *

A {@code

} with attributes stays: its {@code id} may be the target of a link. + */ + private static List removeTrailingParagraphTags(List input) { + // The last token is always END_JAVADOC, and the scan stops at BEGIN_JAVADOC at the latest. + int end = input.size() - 1; + int cut = end; + for (int i = end - 1; i >= 0; i--) { + Token token = input.get(i); + if (token.getType() == PARAGRAPH_OPEN_TAG + && BARE_PARAGRAPH_OPEN_PATTERN.matcher(token.getValue()).matches()) { + cut = i; + } else if (token.getType() != WHITESPACE && token.getType() != PARAGRAPH_CLOSE_TAG) { + break; + } + } + if (cut == end) { + return input; + } + var output = new ArrayList(input.subList(0, cut)); + output.add(input.get(end)); + return List.copyOf(output); + } + + private static final Pattern BARE_PARAGRAPH_OPEN_PATTERN = compile("", CASE_INSENSITIVE); + private static final CharMatcher NEWLINE = CharMatcher.is('\n'); private static boolean hasMultipleNewlines(String s) { diff --git a/open-java-format/src/test/java/com/palantir/javaformat/java/JavadocFormattingTest.java b/open-java-format/src/test/java/com/palantir/javaformat/java/JavadocFormattingTest.java index 0643bfce0..320e3d5d2 100644 --- a/open-java-format/src/test/java/com/palantir/javaformat/java/JavadocFormattingTest.java +++ b/open-java-format/src/test/java/com/palantir/javaformat/java/JavadocFormattingTest.java @@ -1028,6 +1028,73 @@ void removeInitialParagraphTag() { doFormatTest(input, expected); } + @Test + void removeTrailingParagraphTag() { + String[] input = { + "/**", // + " * The client's first name.", + " *", + " *

", + " */", + "class Test {}", + }; + String[] expected = { + "/** The client's first name. */", // + "class Test {}", + }; + doFormatTest(input, expected); + } + + @Test + void removeEveryTrailingParagraphTag() { + String[] input = { + "class Test {", + " /**", + " * Returns nothing.", + " *", + " * @param x the x", + " *

", + " */", + " void f(int x) {}", + "", + " /**", + " * Closed and repeated.", + " *", + " *

", + " *

", + " */", + " void g() {}", + "}", + }; + String[] expected = { + "class Test {", + " /**", + " * Returns nothing.", + " *", + " * @param x the x", + " */", + " void f(int x) {}", + "", + " /** Closed and repeated. */", + " void g() {}", + "}", + }; + doFormatTest(input, expected); + } + + @Test + void keepTrailingParagraphTagWithAttributes() { + String[] input = { + "/**", // + " * Ends with an anchor.", + " *", + " *

", + " */", + "class Test {}", + }; + doFormatTest(input, input); + } + @Test void inferParagraphTags() { String[] input = { From f9bdee0f7b86df3fdef2cf0877f04bcb130ca68f Mon Sep 17 00:00:00 2001 From: Alex Abashev Date: Thu, 19 Nov 2026 19:23:18 +0300 Subject: [PATCH 2/4] Make AlmostJavadoc an error 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. --- ...en-java-format.error-prone-conventions.gradle | 1 + .../javaformat/java/javadoc/CharStream.java | 4 +++- .../javaformat/java/javadoc/JavadocLexer.java | 16 ++++++++-------- 3 files changed, 12 insertions(+), 9 deletions(-) diff --git a/buildSrc/src/main/groovy/open-java-format.error-prone-conventions.gradle b/buildSrc/src/main/groovy/open-java-format.error-prone-conventions.gradle index 0b8e66b63..66fc8ab26 100644 --- a/buildSrc/src/main/groovy/open-java-format.error-prone-conventions.gradle +++ b/buildSrc/src/main/groovy/open-java-format.error-prone-conventions.gradle @@ -25,6 +25,7 @@ tasks.withType(JavaCompile).configureEach { nullaway { handleTestAssertionLibraries = true } + error('AlmostJavadoc') error('CanonicalAnnotationSyntax') error('CollectorMutability') error('DefaultCharset') diff --git a/open-java-format/src/main/java/com/palantir/javaformat/java/javadoc/CharStream.java b/open-java-format/src/main/java/com/palantir/javaformat/java/javadoc/CharStream.java index f74d8eccf..d16bc3103 100644 --- a/open-java-format/src/main/java/com/palantir/javaformat/java/javadoc/CharStream.java +++ b/open-java-format/src/main/java/com/palantir/javaformat/java/javadoc/CharStream.java @@ -42,7 +42,9 @@ boolean tryConsume(String expected) { return true; } - /* + /** + * Like {@link #tryConsume}, but for a match of the pattern at the start of the remaining input. + * * @param pattern the pattern to search for, which must be anchored to match only at position 0 */ boolean tryConsumeRegex(Pattern pattern) { diff --git a/open-java-format/src/main/java/com/palantir/javaformat/java/javadoc/JavadocLexer.java b/open-java-format/src/main/java/com/palantir/javaformat/java/javadoc/JavadocLexer.java index 29637a347..4c36fdb62 100644 --- a/open-java-format/src/main/java/com/palantir/javaformat/java/javadoc/JavadocLexer.java +++ b/open-java-format/src/main/java/com/palantir/javaformat/java/javadoc/JavadocLexer.java @@ -647,15 +647,15 @@ private static boolean hasMultipleNewlines(String s) { 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

" (~400 - * hits in Google-internal code). We will join unnecessarily split "words" (like "foobar") - * in a later step. There's a similar story for braces. I'm not sure I actually need to exclude @ - * or *. TODO(cpovirk): Try removing them. + /** + * We exclude {@code <} so that we don't swallow following HTML tags. This lets us fix up {@code foo

} (~400 + * hits in Google-internal code). We will join unnecessarily split "words" (like {@code foobar}) in a later + * step. There's a similar story for braces. I'm not sure I actually need to exclude {@code @} or {@code *}. + * TODO(cpovirk): Try removing them. * - * Thanks to the "rejoin" step in joinAdjacentLiteralsAndAdjacentWhitespace(), we could get away - * with matching only one character here. That would eliminate the need for the regex entirely. - * That might be faster or slower than what we do now. + *

Thanks to the "rejoin" step in {@link #joinAdjacentLiteralsAndAdjacentWhitespace}, we could get away with + * matching only one character here. That would eliminate the need for the regex entirely. That might be faster or + * slower than what we do now. */ private static final Pattern LITERAL_PATTERN = compile("^.[^ \t\n@<{}*]*", DOTALL); From 1b13814e5a06714abc6f135902b7acdfc92e4bfd Mon Sep 17 00:00:00 2001 From: Alex Abashev Date: Thu, 19 Nov 2026 19:34:29 +0300 Subject: [PATCH 3/4] Leave macos-aarch64 out of the native builds of pull requests 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. --- .github/workflows/ci.yml | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c3966a1cc..f9fb93a58 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -161,7 +161,12 @@ jobs: native: name: native (${{ matrix.platform }}) needs: build - runs-on: ${{ matrix.runner }} + # Each platform's runner, looked up here rather than added by the matrix's `include`: an `include` entry + # puts back a platform that `exclude` takes out. + runs-on: >- + ${{ fromJSON('{"linux-x86-64": "ubuntu-latest", "linux-aarch64": "ubuntu-24.04-arm", + "macos-aarch64": "macos-15", "macos-x86-64": "macos-15-intel", + "windows-x86-64": "windows-latest"}')[matrix.platform] }} timeout-minutes: 90 # bash on Windows too, so that every step reads the same on every runner. defaults: @@ -170,17 +175,12 @@ jobs: strategy: fail-fast: false matrix: - include: - - platform: linux-x86-64 - runner: ubuntu-latest - - platform: linux-aarch64 - runner: ubuntu-24.04-arm - - platform: macos-aarch64 - runner: macos-15 - - platform: macos-x86-64 - runner: macos-15-intel - - platform: windows-x86-64 - runner: windows-latest + platform: [linux-x86-64, linux-aarch64, macos-aarch64, macos-x86-64, windows-x86-64] + # Pull requests leave out macos-aarch64. 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 of waiting. + # Pushes to a release line still build it, and so does the release. + exclude: + - platform: ${{ github.event_name == 'pull_request' && 'macos-aarch64' || 'none' }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 From 4a371f578b9ce774699bdfbb28b4bc8c86970808 Mon Sep 17 00:00:00 2001 From: Alex Abashev Date: Thu, 19 Nov 2026 22:54:24 +0300 Subject: [PATCH 4/4] Build the native images on a list of runners, without macOS arm64 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. --- .github/workflows/ci.yml | 24 +++++++++++------------- README.md | 4 ++-- mise.toml | 2 +- 3 files changed, 14 insertions(+), 16 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f9fb93a58..a1b9c83a6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -159,14 +159,9 @@ jobs: # One explicit job per target, so every binary we ship is traceable to a named run. native: - name: native (${{ matrix.platform }}) + name: native (${{ matrix.runner }}) needs: build - # Each platform's runner, looked up here rather than added by the matrix's `include`: an `include` entry - # puts back a platform that `exclude` takes out. - runs-on: >- - ${{ fromJSON('{"linux-x86-64": "ubuntu-latest", "linux-aarch64": "ubuntu-24.04-arm", - "macos-aarch64": "macos-15", "macos-x86-64": "macos-15-intel", - "windows-x86-64": "windows-latest"}')[matrix.platform] }} + runs-on: ${{ matrix.runner }} timeout-minutes: 90 # bash on Windows too, so that every step reads the same on every runner. defaults: @@ -175,12 +170,15 @@ jobs: strategy: fail-fast: false matrix: - platform: [linux-x86-64, linux-aarch64, macos-aarch64, macos-x86-64, windows-x86-64] - # Pull requests leave out macos-aarch64. 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 of waiting. - # Pushes to a release line still build it, and so does the release. - exclude: - - platform: ${{ github.event_name == 'pull_request' && 'macos-aarch64' || 'none' }} + runner: + - ubuntu-latest + - ubuntu-24.04-arm + # macOS arm64 is left out: GitHub's runners for it are scarce, and from 17 to 19 November 2026 it found + # none for 13 of the job's 21 pull-request runs, each failing after 15 minutes of waiting. The release + # still builds it. + # - macos-15 + - macos-15-intel + - windows-latest steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 diff --git a/README.md b/README.md index 5e3d29ef2..9ee8a279d 100644 --- a/README.md +++ b/README.md @@ -192,10 +192,10 @@ mise run ci:native # actually run the linux-aarch64 native job Two caveats: -- **act cannot containerise macOS**, so the `macos-aarch64` leg has to be checked by building the +- **act cannot containerise macOS**, so the `macos-15-intel` leg has to be checked by building the native image on a Mac. - **On an Apple Silicon host** the `ubuntu-24.04` container runs as arm64, so the job labelled - `linux-x86-64` produces an aarch64 binary locally. Fine for exercising the workflow, not a + `ubuntu-latest` produces an aarch64 binary locally. Fine for exercising the workflow, not a substitute for real CI. ## License and attribution diff --git a/mise.toml b/mise.toml index 3f89f0094..0dc300c06 100644 --- a/mise.toml +++ b/mise.toml @@ -18,7 +18,7 @@ run = "act push --job build --env JAVA_HOME=/opt/hostedtoolcache/Java_Temurin-Ho [tasks."ci:native"] description = "Run the linux-aarch64 native job locally in Docker" -run = "act push --job native --matrix platform:linux-aarch64" +run = "act push --job native --matrix runner:ubuntu-24.04-arm" # ---- GitHub Actions secrets ---- # Read from 1Password at apply time; nothing secret is stored in the repo. Requires gh