Skip to content

Commit 0030c96

Browse files
committed
Drop the <p> tags that end a Javadoc comment
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
1 parent 9b11043 commit 0030c96

2 files changed

Lines changed: 98 additions & 1 deletion

File tree

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

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -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) {

‎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)