Tooltips for enum values are rendered incorrectly in documentation of configuration properties

[yrodiere]

Describe the bug

See for example https://quarkus.io/guides/scheduler#scheduler-configuration-reference

Expected behavior

All enum values should be rendered correctly.

Actual behavior

Only the first enum value is rendered correctly, the other ones seem off:

How to Reproduce?

No response

Output of uname -a or ver

No response

Output of java -version

No response

GraalVM version (if different from Java)

No response

Quarkus version or git rev

No response

Build tool (ie. output of mvnw --version or gradlew --version)

No response

Additional information

No response

[quarkus-bot]

/cc @MichalMaler (documentation), @ebullient (documentation), @inoxx03 (documentation), @michelle-purcell (documentation), @rolfedh (documentation), @sheilamjones (documentation), @sunayna15 (documentation)

[nderwin]

I think I've narrowed this down to a problem with how the <p> tag is being interpreted in the javadocs for the enum values - these are being replaced with 2 newlines (\n) when translated into the asciidoc file, but that seems to break the formatting into HTML.

Either the javadoc could be updated to remove the paragraph tags, or the parser updated to use asciidoc hard line breaks.

Thoughts?

[yrodiere]

these are being replaced with 2 newlines (\n) when translated into the asciidoc file

Right, that's the correct translation.

that seems to break the formatting into HTML.

the parser updated to use asciidoc hard line breaks

I'm not sure this would make sense as I think the parser is used in other contexts. Also, if you mean <br>, that's not the correct translation for <p>.

Thoughts?

I'm not sure why this breaks exactly so this may be irrelevant, but can't we wrap the generated asciidoc of each tooltip into an open block?

[yrodiere]

these are being replaced with 2 newlines (\n) when translated into the asciidoc file

Right, that's the correct translation.

that seems to break the formatting into HTML.

the parser updated to use asciidoc hard line breaks

I'm not sure this would make sense as I think the parser is used in other contexts. Also, if you mean <br>, that's not the correct translation for <p>.

Thoughts?

I'm not sure why this breaks exactly so this may be irrelevant, but can't we wrap the generated asciidoc for the description of each enum into an open block?

[nderwin]

No, not <br>, but +\n instead of \n.

I'm not sure about the open block, if it would work inside the table cell that contains the enum values, or if having multiple open blocks would work.

[yrodiere]

Only one way to find out :)

Personally I'd rather avoid changing the way <p> is translated by the parser because it would potentially affect a lot more than just these tooltips (I think?). At least open blocks can be used to wrap tooltips specifically and nothing else.

But if we really have to... whatever works and doesn't break formatting for the rest of the guides is fine to me.

[nderwin]

Good news - I created a small reproducer so the build cycle is shorter; bad news - neither the open blocks nor the asciidoc hard line breaks seemed to help. What did help, was to smash it all together in one line (but then I don't get the tooltips at all, probably an issue with the reproducer).

[gsmet]

Probably a good idea to share your reproducer so that others can have a look.

[nderwin]

mvn clean install in the greeting-extension directory; the HTML docs are in the docs module in the target directory.

greeting-extension.zip

[nderwin]

I did just confirm if I take the <p> tags out of the javadoc, then it generates the HTML without the extra noise (but I'd rather not have that as the solution either):

[nderwin]

An updated reproducer that generates the HTML page with the same magic that quarkus.io uses, giving the tooltip hover.

It boils down to those newlines inside of the square brackets surrounding the tooltip text. If we take those out, it'll generate the HTML nicely. I haven't stumbled onto an asciidoc combo to allow leaving those in... yet.

greeting-extension.zip

[michalvavrik]

thanks for looking into this @nderwin

[michalvavrik]

It boils down to those newlines inside of the square brackets surrounding the tooltip text. If we take those out, it'll generate the HTML nicely. I haven't stumbled onto an asciidoc combo to allow leaving those in... yet.

I'm only judging by your analysis and I'll be happy if you come with better solution, but if it goes down to the newlines inside tooltip description, I'd just strip it. Tooltip description is inline block and you can't expect paragraphs work there anyway.