Skip to content

Commit 3453f13

Browse files
authored
Merge pull request #247 from openjavaformat/abashev/javadoc-drop-an-empty-trailing-p-tag
Drop the <p> tags that end a Javadoc comment
2 parents 442f75b + 93e1a0b commit 3453f13

7 files changed

Lines changed: 126 additions & 27 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,7 @@ jobs:
159159

160160
# One explicit job per target, so every binary we ship is traceable to a named run.
161161
native:
162-
name: native (${{ matrix.platform }})
162+
name: native (${{ matrix.runner }})
163163
needs: build
164164
runs-on: ${{ matrix.runner }}
165165
timeout-minutes: 90
@@ -170,17 +170,15 @@ jobs:
170170
strategy:
171171
fail-fast: false
172172
matrix:
173-
include:
174-
- platform: linux-x86-64
175-
runner: ubuntu-latest
176-
- platform: linux-aarch64
177-
runner: ubuntu-24.04-arm
178-
- platform: macos-aarch64
179-
runner: macos-15
180-
- platform: macos-x86-64
181-
runner: macos-15-intel
182-
- platform: windows-x86-64
183-
runner: windows-latest
173+
runner:
174+
- ubuntu-latest
175+
- ubuntu-24.04-arm
176+
# macOS arm64 is left out: GitHub's runners for it are scarce, and from 17 to 19 November 2026 it found
177+
# none for 13 of the job's 21 pull-request runs, each failing after 15 minutes of waiting. The release
178+
# still builds it.
179+
# - macos-15
180+
- macos-15-intel
181+
- windows-latest
184182

185183
steps:
186184
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -192,10 +192,10 @@ mise run ci:native # actually run the linux-aarch64 native job
192192

193193
Two caveats:
194194

195-
- **act cannot containerise macOS**, so the `macos-aarch64` leg has to be checked by building the
195+
- **act cannot containerise macOS**, so the `macos-15-intel` leg has to be checked by building the
196196
native image on a Mac.
197197
- **On an Apple Silicon host** the `ubuntu-24.04` container runs as arm64, so the job labelled
198-
`linux-x86-64` produces an aarch64 binary locally. Fine for exercising the workflow, not a
198+
`ubuntu-latest` produces an aarch64 binary locally. Fine for exercising the workflow, not a
199199
substitute for real CI.
200200

201201
## License and attribution

‎buildSrc/src/main/groovy/open-java-format.error-prone-conventions.gradle‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ tasks.withType(JavaCompile).configureEach {
2525
nullaway {
2626
handleTestAssertionLibraries = true
2727
}
28+
error('AlmostJavadoc')
2829
error('CanonicalAnnotationSyntax')
2930
error('CollectorMutability')
3031
error('DefaultCharset')
@@ -37,6 +38,7 @@ tasks.withType(JavaCompile).configureEach {
3738
error('RefactorSwitch')
3839
error('SameNameButDifferent')
3940
error('StringConcatToTextBlock')
41+
error('UnrecognisedJavadocTag')
4042
error('UnusedVariable')
4143
disable('IsInstanceLambdaUsage')
4244
disable('LexicographicalAnnotationAttributeListing')

‎mise.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ run = "act push --job build --env JAVA_HOME=/opt/hostedtoolcache/Java_Temurin-Ho
1818

1919
[tasks."ci:native"]
2020
description = "Run the linux-aarch64 native job locally in Docker"
21-
run = "act push --job native --matrix platform:linux-aarch64"
21+
run = "act push --job native --matrix runner:ubuntu-24.04-arm"
2222

2323
# ---- GitHub Actions secrets ----
2424
# Read from 1Password at apply time; nothing secret is stored in the repo. Requires gh

‎open-java-format/src/main/java/com/palantir/javaformat/java/javadoc/CharStream.java‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,9 @@ boolean tryConsume(String expected) {
4242
return true;
4343
}
4444

45-
/*
45+
/**
46+
* Like {@link #tryConsume}, but for a match of the pattern at the start of the remaining input.
47+
*
4648
* @param pattern the pattern to search for, which must be anchored to match only at position 0
4749
*/
4850
boolean tryConsumeRegex(Pattern pattern) {

‎open-java-format/src/main/java/com/palantir/javaformat/java/javadoc/JavadocLexer.java‎

Lines changed: 41 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -80,8 +80,8 @@ static List<Token> lex(String input) throws LexException {
8080
/**
8181
* Strips the margin from every continuation line: the {@code *} prefix (with the space after it) from lines that
8282
* have one, and the comment's own indentation from lines that do not. What remains of a bare line's indentation is
83-
* relative to the comment, as on {@code *} lines after their {@code * }, so a {@code <pre>{@code} block written
84-
* without the {@code *} margin keeps its shape for {@link #deindentPreCodeBlocks}.
83+
* relative to the comment, as on {@code *} lines after their {@code * }, so a <code>&lt;pre&gt;&#123;@code</code>
84+
* block written without the {@code *} margin keeps its shape for {@link #deindentPreCodeBlocks}.
8585
*
8686
* <p>The indentation stripped from bare lines is the smaller of the shortest {@code *} prefix and the shortest
8787
* indentation of a bare line, so a bare line is never cut into and lines of both kinds stay aligned with each
@@ -173,7 +173,8 @@ private List<Token> generateTokens() throws LexException {
173173
result = joinAdjacentLiteralsAndAdjacentWhitespace(result);
174174
result = inferParagraphTags(result);
175175
result = optionalizeSpacesAfterLinks(result);
176-
return deindentPreCodeBlocks(result);
176+
result = deindentPreCodeBlocks(result);
177+
return removeTrailingParagraphTags(result);
177178
}
178179

179180
private Token readToken() throws LexException {
@@ -574,6 +575,35 @@ private static void deindentPreCodeBlock(List<Token> output, PeekingIterator<Tok
574575
}
575576
}
576577

578+
/**
579+
* Remove the {@code <p>} tags at the end of the comment, and the whitespace and {@code </p>} tags among them.
580+
* Nothing follows such a tag, but the writer would still put it on a line of its own after a blank one.
581+
*
582+
* <p>A {@code <p>} with attributes stays: its {@code id} may be the target of a link.
583+
*/
584+
private static List<Token> removeTrailingParagraphTags(List<Token> input) {
585+
// The last token is always END_JAVADOC, and the scan stops at BEGIN_JAVADOC at the latest.
586+
int end = input.size() - 1;
587+
int cut = end;
588+
for (int i = end - 1; i >= 0; i--) {
589+
Token token = input.get(i);
590+
if (token.getType() == PARAGRAPH_OPEN_TAG
591+
&& BARE_PARAGRAPH_OPEN_PATTERN.matcher(token.getValue()).matches()) {
592+
cut = i;
593+
} else if (token.getType() != WHITESPACE && token.getType() != PARAGRAPH_CLOSE_TAG) {
594+
break;
595+
}
596+
}
597+
if (cut == end) {
598+
return input;
599+
}
600+
var output = new ArrayList<Token>(input.subList(0, cut));
601+
output.add(input.get(end));
602+
return List.copyOf(output);
603+
}
604+
605+
private static final Pattern BARE_PARAGRAPH_OPEN_PATTERN = compile("<p\\s*/?\\s*>", CASE_INSENSITIVE);
606+
577607
private static final CharMatcher NEWLINE = CharMatcher.is('\n');
578608

579609
private static boolean hasMultipleNewlines(String s) {
@@ -617,15 +647,15 @@ private static boolean hasMultipleNewlines(String s) {
617647
private static final Pattern BR_PATTERN = openTagPattern("br");
618648
private static final Pattern SNIPPET_TAG_OPEN_PATTERN = compile("^[{]@snippet\\b");
619649
private static final Pattern INLINE_TAG_OPEN_PATTERN = compile("^[{]@\\w*");
620-
/*
621-
* We exclude < so that we don't swallow following HTML tags. This lets us fix up "foo<p>" (~400
622-
* hits in Google-internal code). We will join unnecessarily split "words" (like "foo<b>bar</b>")
623-
* in a later step. There's a similar story for braces. I'm not sure I actually need to exclude @
624-
* or *. TODO(cpovirk): Try removing them.
650+
/**
651+
* We exclude {@code <} so that we don't swallow following HTML tags. This lets us fix up {@code foo<p>} (~400
652+
* hits in Google-internal code). We will join unnecessarily split "words" (like {@code foo<b>bar</b>}) in a later
653+
* step. There's a similar story for braces. I'm not sure I actually need to exclude {@code @} or {@code *}.
654+
* TODO(cpovirk): Try removing them.
625655
*
626-
* Thanks to the "rejoin" step in joinAdjacentLiteralsAndAdjacentWhitespace(), we could get away
627-
* with matching only one character here. That would eliminate the need for the regex entirely.
628-
* That might be faster or slower than what we do now.
656+
* <p>Thanks to the "rejoin" step in {@link #joinAdjacentLiteralsAndAdjacentWhitespace}, we could get away with
657+
* matching only one character here. That would eliminate the need for the regex entirely. That might be faster or
658+
* slower than what we do now.
629659
*/
630660
private static final Pattern LITERAL_PATTERN = compile("^.[^ \t\n@<{}*]*", DOTALL);
631661

‎open-java-format/src/test/java/com/palantir/javaformat/java/JavadocFormattingTest.java‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1028,6 +1028,73 @@ void removeInitialParagraphTag() {
10281028
doFormatTest(input, expected);
10291029
}
10301030

1031+
@Test
1032+
void removeTrailingParagraphTag() {
1033+
String[] input = {
1034+
"/**", //
1035+
" * The client's first name.",
1036+
" *",
1037+
" * <p>",
1038+
" */",
1039+
"class Test {}",
1040+
};
1041+
String[] expected = {
1042+
"/** The client's first name. */", //
1043+
"class Test {}",
1044+
};
1045+
doFormatTest(input, expected);
1046+
}
1047+
1048+
@Test
1049+
void removeEveryTrailingParagraphTag() {
1050+
String[] input = {
1051+
"class Test {",
1052+
" /**",
1053+
" * Returns nothing.",
1054+
" *",
1055+
" * @param x the x",
1056+
" * <p>",
1057+
" */",
1058+
" void f(int x) {}",
1059+
"",
1060+
" /**",
1061+
" * Closed and repeated.",
1062+
" *",
1063+
" * <p></p>",
1064+
" * <P/>",
1065+
" */",
1066+
" void g() {}",
1067+
"}",
1068+
};
1069+
String[] expected = {
1070+
"class Test {",
1071+
" /**",
1072+
" * Returns nothing.",
1073+
" *",
1074+
" * @param x the x",
1075+
" */",
1076+
" void f(int x) {}",
1077+
"",
1078+
" /** Closed and repeated. */",
1079+
" void g() {}",
1080+
"}",
1081+
};
1082+
doFormatTest(input, expected);
1083+
}
1084+
1085+
@Test
1086+
void keepTrailingParagraphTagWithAttributes() {
1087+
String[] input = {
1088+
"/**", //
1089+
" * Ends with an anchor.",
1090+
" *",
1091+
" * <p id=\"end\">",
1092+
" */",
1093+
"class Test {}",
1094+
};
1095+
doFormatTest(input, input);
1096+
}
1097+
10311098
@Test
10321099
void inferParagraphTags() {
10331100
String[] input = {

0 commit comments

Comments
 (0)