How do you escape curly braces in javadoc inline tags, such as the {@code} tag

Solution 1:

Not so much an answer as a workaround, but if you replace {@code ...} with the old version <code>...</code> it will render curly braces how you expect.

<code>{person} == ${person}</code>

Unfortunately, this breaks angle brackets, so to the original question you need to escape these:

<code>&lt;custom:meatball color="&lt;%= Meatball.RED %&gt; nincompoop="${person}" /&gt;</code>

You can even cheat here by getting Notepad++ to do that for you, with the handy TextFX -> convert -> Encode HTML (&<>").

This does at least have the benefit that everything renders nicely both in the generated Javadoc and in Eclipse in the Javadoc view, which doesn't appear to understand } and friends.

Solution 2:

Try using HTML escapes:

$&#123;person&#125; == ${person}

Solution 3:

bodunbodun solution works as it usually happens that you have newline as well in the javadocs. HTML escapes won't work if you want both { and newline

<pre>
{@code
<foo bar="}${bar}{@code"/>
<bar foo="}${foo}{@code"/>
}
</pre>

will give you

<foo bar="${bar}" />
<bar foo="${foo}" />

Solution 4:

I had the same problem actually - none of propositions have worked for me (HTML escapes do not work for whatever reason). If that helps - try closing the {@code} before problematic symbol and reopen it after, like this:

{@code nincompoop="}${person}{@code" />}

This doesn't seem the solution, but it works, and does not break formatting if used carefully :)

Solution 5:

At least as of Java 1.8.0_31, I can't reproduce the issue anymore. Your input renders as expected:

<code>&lt;custom:meatball color="&lt;%= Meatball.RED %&gt; nincompoop="${person}" /&gt;</code>

My tests indicate that javadoc takes into consideration balanced curly braces inside @code, and only ends it when the corresponding curly brace is found.

So if the code has balanced curly braces {} like your example, it now works as expected.

But I still don't know what to do with unbalanced curly braces like:

{@code printf"}<b>outside</b>"}

Also, the behavior depends on which inline tag you are using. man javadoc explicitly says that for @link:

If you need to use the right brace (}) inside the label, then use the HTML entity notation &#125;.

So in that case it is impossible to do any better.

Unfortunately, I couldn't find a similar quote for @code which backs my experiments.