Strange render issues of unordered lists used in Javadoc comments of Java 23

1

Can’t find a better place to ask this, so apologiez in advance if there was a better place for discussing this.

I use Markdown in Javadoc comments, because Java 23 implemented support for Markdown in them using a new syntax.
Now, they mention on their docs page, that they support the CommonMark Spec for the overall markdown syntax… However, it’s not mentioned what tool/parser they actively use for converting the text into the final HTML, but my current guess is commonmark.js, as I find the same visual issue on the demo page as I currently encounter with the rendered page itself.

The issue I encounter, is the fact that parts of an unordered list render as empty entries, without any real logical explanation for why this happens exactly.

In particular, I have the following comment set for my docs:

/// Creates an "empty" PlayerEntry with the following values:
///
///   - [#motd()]: Empty List
///   - [#players()]: Empty List
///   - [#playerCountText()]: Empty String
///   - [#favicon()]: Empty String
///   - [#hidePlayersEnabled()]: `NullBool.NOT_SET`
///   - [#extraPlayersEnabled()]: `NullBool.NOT_SET`
///   - [#maxPlayersEnabled()]: `NullBool.NOT_SET`
///   - [#onlinePlayersEnabled()]: `NullBool.NOT_SET`
///   - [#extraPlayersCount()]: `null`
///   - [#maxPlayersCount()]: `null`
///   - [#onlinePlayersCount()]: `null`
/// 
/// This is equal to just doing `new ProfileEntry.Builder().build()`.
///
/// @return New ProfileEntry Instance with empty/null values set.

Now, I first want to make sure I explain a few minor things to make it clear and avoid confusion/misunderstandings:

  • Javadocs remove the leading /// and any leading whitespaces until one line becomes “level” (has no leading whitespaces), meaning the lists should keep their 2 space indents.
  • Javadocs allows defining links to packages, objects, classes, etc. by using [<path.to.thing>] or [display text][<path.to.thing>]. Using the former creates a Link to the specified object, package, … with its name being displayed in <code> tags, so for example, [#motd()] is converted to <a href="#motd()"><code>motd()</code></a>
  • @return is a tag used to describe what a method or similar may return. I will discard it in the follow-up sections as they aren’t relevant to the issue I encounter.

With all this covered, the Markdown that would be rendered is this:

Creates an "empty" PlayerEntry with the following values:

  - [#motd()]: Empty List
  - [#players()]: Empty List
  - [#playerCountText()]: Empty String
  - [#favicon()]: Empty String
  - [#hidePlayersEnabled()]: `NullBool.NOT_SET`
  - [#extraPlayersEnabled()]: `NullBool.NOT_SET`
  - [#maxPlayersEnabled()]: `NullBool.NOT_SET`
  - [#onlinePlayersEnabled()]: `NullBool.NOT_SET`
  - [#extraPlayersCount()]: `null`
  - [#maxPlayersCount()]: `null`
  - [#onlinePlayersCount()]: `null`

This is equal to just doing `new ProfileEntry.Builder().build()`.

However, the final result (The HTML) is this:

<p>Creates an &quot;empty&quot; PlayerEntry with the following values:</p>
<ul>
<li><a href="#motd()"><code>motd()</code></a>: Empty List</li>
<li><a href="#players()"><code>players()</code></a>: Empty List</li>
<li><a href="#playerCountText()"><code>playerCountText()</code></a>: Empty String</li>
<li><a href="#favicon()"><code>favicon()</code></a>: Empty String</li>
<li></li>
<li></li>
<li></li>
<li></li>
<li></li>
<li></li>
<li></li>
</ul>
<p>This is equal to just doing <code>new ProfileEntry.Builder().build()</code>.</p>

As you can see, any list entry after - [#favicon()]: Empty String for some reason renders as an empty entry in the list.

As mentioned before do I assume the Javadoc tool uses commonmark.js, as I encounter the same issue within that tool when trying it on the demo page.
A permalink to that test is here.

Now, my main question is simply: Why is this happening? Is this some random edge-case of the parser treating the text after favicon line as special? Is it some list limitation? Something else?

I would really apreciate some input on this, as I may report this to the Javadoc devs too, but first would like some input on this matter here to have a bit more “evidence” on what could cause all this…

Thanks.

2

From a CM point of view, the code looks fine and should not generate empty list entries.

I notice that all affected lines have a code span aber the common which is either null or NullBool.NOT_SET.

Did you try to shuffle the lines around and create a minimal reproducible problem?

3

I did now and by the looks of it are lines with the null and NullBool.NOT_SET text not displaying properly…
Test 1

I also tested with completely random words, and this one found the cause: No spaces
Test 2

As you can see by this test do the lines with text containing spaces show up. So I guess the parser considers text without spaces as reference link declarations, hiding them as it expects them to be referenced, when they aren’t.

For now I can just remove the colons, or probs use the HTML entity (&col; iirc) for it, but not sure if this can be fixed in the long run. As mentioned is the javadoc parser using the [path] and [text][path] to deine links to classes, so people can and will encounter these issues eventually, just like I did…

4

It’s because the empty lines are link reference definitions. You can tell, because of what the visible link points to in this example:

  - [#hidePlayersEnabled()]: `NullBool.NOT_SET`
  - [#hidePlayersEnabled()]: this line is visible

The first line is blank. The second line starts with a link that points at the relative URL “NullBool.NOT_SET”.

(Interesting note: djot does this, too.)

5

Yeah, I already had my suspicion that this may be the relative link feature causing an issue… Need to find a way to contact the people responsible for the Javadoc tool to report this… Perhaps they could find a way (i.e. by disabling this handling?) or at least provide a note informing about this caveat.