如何在javadoc内联标记中转义花括号，例如{@code}标记

/**
 * 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.

“$ {person}”部分会破坏文档注释,因为它使用花括号。

7 个解决方案

#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 ...} ... ,它将呈现大括号的期望。

<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 (&<>").

您甚至可以通过让Notepad ++为您做到这一点来欺骗,方便的TextFX - >转换 - >编码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.

这至少有一个好处,一切都在生成的Javadoc和Javadoc视图中的Eclipse中很好地呈现,这看起来并不理解和朋友。

#2

Try using HTML escapes:

尝试使用HTML转义:

${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

bodunbodun解决方案的工作原理通常发生在javadocs中也有换行符。如果你想要{和换行符',HTML转义将不起作用

<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:

我实际上遇到了同样的问题 - 没有一个命题对我有用(HTML转义因任何原因都不起作用)。如果这有帮助 - 尝试在有问题的符号之前关闭{@code}并在之后重新打开它,如下所示:

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

{@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:

至少从Java 1.8.0_31开始,我再也无法重现这个问题了。您的输入按预期呈现:

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

我的测试表明,javadoc考虑了@code中的平衡花括号,并且只有在找到相应的花括号时才结束它。

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:

此外,行为取决于您使用的内联标记。 man javadoc明确地说@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.

不幸的是,我找不到类似的@code引用我的实验。

#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

找到了另一种不太出色的解决方法。它比其他更好还是更差?我会让你决定的。获取{@code}部分并将其替换为 。 (这使得它因角度括号而全部消失。)取第一个 <并将其包裹在{@literal}中,使其看起来像{@literal <}。现在一切都会好起来,并且在代码中并没有被狠狠地宰杀。最终结果如下所示< p>

/**
 * 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:

或者,如果您不喜欢{@literal <},那么您可以使用<代替。结果如下所示:

/**
 * 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.

使用{@literal},这样做{@literal}}。适用于我的测试。

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
 * 
 */