How do you escape curly braces in javadoc inline t

问题:

/**
 * Gets the meatball icon for a nincompoop.
 * 
 * <p>
 * Example: {@code <custom:meatball color="<%= Meatball.RED %> nincompoop="${person}" />}
 * 
 * @author King Cong
 * 
 */

The "${person}" part breaks the doc comment because it uses curly braces.

回答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.

回答2:

Try using HTML escapes:

${person} == ${person}

回答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}" />

回答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 :)

回答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 }.

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.

回答6:

Found another less than stellar workaround for this. Is it better or worse than the other ones? I'll let you decide. Take the {@code } part and replace it with <code> </code>. (This makes it all disappear because of the angle braces.) The take the very first < and wrap it in {@literal }, making it look like this {@literal<}. Now everything will show up fine, and it's not too horribly slaughtered in the code. The final result looks like this

/**
 * Gets the meatball icon for a nincompoop.
 * 
 * <p>
 * Example: <code>{@literal<}custom:meatball color="<%= Meatball.RED %> nincompoop="${person}" /></code>
 * 
 * @author King Cong
 * 
 */

Alternatively, if you don't like the {@literal<}, then you could use < instead. The result would look like this:

/**
 * Gets the meatball icon for a nincompoop.
 * 
 * <p>
 * Example: <code> &lt;custom:meatball color="<%= Meatball.RED %> nincompoop="${person}" /></code>
 * 
 * @author King Cong
 * 
 */

Neither are great solutions, but they do work.

回答7:

Use the {@literal}, so do this {@literal } }. Works in my tests.

So for your case, it would look like this:

/**
 * Gets the meatball icon for a nincompoop.
 * 
 * <p>
 * Example: {@code <custom:meatball color="<%= Meatball.RED %> nincompoop="${person{@literal } }" />}
 * 
 * @author King Cong
 * 
 */