Skip to content

Fix nested list handling in Javadoc to AsciiDoc converter #53689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gsmet merged 1 commit into from
Apr 24, 2026
+115 −10
Merged

Fix nested list handling in Javadoc to AsciiDoc converter #53689

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 36 additions & 9 deletions ...kus/annotation/processor/documentation/config/formatter/JavadocToAsciidocTransformer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,8 @@ public final class JavadocToAsciidocTransformer {
private static final String SUB_SCRIPT_ASCIDOC_STYLE = "~";
private static final String SUPER_SCRIPT_ASCIDOC_STYLE = "^";
private static final String SMALL_ASCIDOC_STYLE = "[.small]";
private static final String ORDERED_LIST_ITEM_ASCIDOC_STYLE = " . ";
private static final String UNORDERED_LIST_ITEM_ASCIDOC_STYLE = " - ";
private static final String ORDERED_LIST_MARKER = ".";
private static final String UNORDERED_LIST_MARKER = "*";
private static final String UNDERLINE_ASCIDOC_STYLE = "[.underline]";
private static final String LINE_THROUGH_ASCIDOC_STYLE = "[.line-through]";
private static final String HARD_LINE_BREAK_ASCIDOC_STYLE = " +\n";
Expand Down Expand Up @@ -189,17 +189,32 @@ private static void htmlToAsciidoc(StringBuilder sb, Node node, boolean inlineMa
break;
case ORDERED_LIST_NODE:
case UN_ORDERED_LIST_NODE:
newLine(sb);
if (context.listDepth > 0) {
// Nested list: we're already on a new line from the parent list item,
// no need for an extra newline
} else {
newLine(sb);
}
context.listDepth++;
htmlToAsciidoc(sb, childNode, inlineMacroMode, context);
newLine(sb);
newLine(sb);
context.listDepth--;
if (context.listDepth == 0) {
newLine(sb);
newLine(sb);
}
break;
case LIST_ITEM_NODE:
final String marker = childNode.parentNode().nodeName().equals(ORDERED_LIST_NODE)
? ORDERED_LIST_ITEM_ASCIDOC_STYLE
: UNORDERED_LIST_ITEM_ASCIDOC_STYLE;
final String listMarker = childNode.parentNode().nodeName().equals(ORDERED_LIST_NODE)
? ORDERED_LIST_MARKER
: UNORDERED_LIST_MARKER;
newLine(sb);
sb.append(marker);
sb.append(' ');
for (int i = 0; i < context.listDepth; i++) {
sb.append(listMarker);
}
sb.append(' ');
// Track that we're in a list item to strip leading whitespace from the first text node
context.firstTextInListItem = true;
htmlToAsciidoc(sb, childNode, inlineMacroMode, context);
break;
case LINK_NODE:
Expand Down Expand Up @@ -273,6 +288,16 @@ private static void htmlToAsciidoc(StringBuilder sb, Node node, boolean inlineMa
break;
}

// Trim leading whitespace for the first text node inside a list item
// (HTML formatting often introduces extra spaces/newlines)
if (context.firstTextInListItem) {
text = text.stripLeading();
context.firstTextInListItem = false;
if (text.isEmpty()) {
break;
}
}

// Indenting the first line of a paragraph by one or more spaces makes the block literal
// Please see https://docs.asciidoctor.org/asciidoc/latest/verbatim/literal-blocks/ for more info
// This prevents literal blocks f.e. after <br>
Expand Down Expand Up @@ -553,5 +578,7 @@ private static class Context {

boolean inTable;
boolean firstTableRow;
int listDepth;
boolean firstTextInListItem;
}
}
80 changes: 79 additions & 1 deletion .../processor/documentation/config/formatter/JavadocToAsciidocTransformerConfigItemTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ public void parseJavaDocWithLiTagsInsideUlTag() {
"<li>2</li>\n" +
"</ul>" +
"";
String expectedOutput = "List:\n\n - 1\n - 2";
String expectedOutput = "List:\n\n * 1\n * 2";
ParsedJavadoc parsed = JavadocUtil.parseConfigItemJavadoc(javaDoc);
String description = JavadocToAsciidocTransformer.toAsciidoc(parsed.description(), parsed.format());

Expand All @@ -143,6 +143,84 @@ public void parseJavaDocWithLiTagsInsideOlTag() {
assertEquals(expectedOutput, description);
}

@Test
public void parseJavaDocWithNestedUnorderedList() {
String javaDoc = "List:" +
"<ul>\n" +
"<li>First sentence. Second sentence.</li>\n" +
"<li>\n" +
"And some nested bullet list:\n" +
"<ul>\n" +
"<li>Element 1 with one sentence. And another sentence.</li>\n" +
"<li>Element 2 with sentence 2. And yet another sentence.</li>\n" +
"</ul>\n" +
"</li>\n" +
"</ul>";
String expectedOutput = "List:\n\n * First sentence. Second sentence.\n * And some nested bullet list:\n ** Element 1 with one sentence. And another sentence.\n ** Element 2 with sentence 2. And yet another sentence.";
ParsedJavadoc parsed = JavadocUtil.parseConfigItemJavadoc(javaDoc);
String description = JavadocToAsciidocTransformer.toAsciidoc(parsed.description(), parsed.format());

assertEquals(expectedOutput, description);
}

@Test
public void parseJavaDocWithNestedOrderedList() {
String javaDoc = "List:" +
"<ol>\n" +
"<li>Item 1</li>\n" +
"<li>\n" +
"Item 2 with nested list:\n" +
"<ol>\n" +
"<li>Sub 1</li>\n" +
"<li>Sub 2</li>\n" +
"</ol>\n" +
"</li>\n" +
"</ol>";
String expectedOutput = "List:\n\n . Item 1\n . Item 2 with nested list:\n .. Sub 1\n .. Sub 2";
ParsedJavadoc parsed = JavadocUtil.parseConfigItemJavadoc(javaDoc);
String description = JavadocToAsciidocTransformer.toAsciidoc(parsed.description(), parsed.format());

assertEquals(expectedOutput, description);
}

@Test
public void parseJavaDocWithDeeplyNestedLists() {
String javaDoc = "List:" +
"<ul>\n" +
"<li>Level 1\n" +
"<ul>\n" +
"<li>Level 2\n" +
"<ul>\n" +
"<li>Level 3</li>\n" +
"</ul>\n" +
"</li>\n" +
"</ul>\n" +
"</li>\n" +
"</ul>";
String expectedOutput = "List:\n\n * Level 1\n ** Level 2\n *** Level 3";
ParsedJavadoc parsed = JavadocUtil.parseConfigItemJavadoc(javaDoc);
String description = JavadocToAsciidocTransformer.toAsciidoc(parsed.description(), parsed.format());

assertEquals(expectedOutput, description);
}

@Test
public void parseJavaDocWithMixedNestedLists() {
String javaDoc = "List:" +
"<ul>\n" +
"<li>Unordered item\n" +
"<ol>\n" +
"<li>Ordered sub-item</li>\n" +
"</ol>\n" +
"</li>\n" +
"</ul>";
String expectedOutput = "List:\n\n * Unordered item\n .. Ordered sub-item";
ParsedJavadoc parsed = JavadocUtil.parseConfigItemJavadoc(javaDoc);
String description = JavadocToAsciidocTransformer.toAsciidoc(parsed.description(), parsed.format());

assertEquals(expectedOutput, description);
}

@Test
public void parseJavaDocWithLinkInlineSnippet() {
String javaDoc = "{@link firstlink} {@link #secondlink} \n {@linkplain #third.link}";
Expand Down
Loading