如何在 javadoc 内联标签中转义大括号，例如 {@code} 标签答案

【问题标题】：How do you escape curly braces in javadoc inline tags, such as the {@code} tag如何在 javadoc 内联标签中转义大括号，例如 {@code} 标签
【发布时间】：2023-07-09 10:20:02
【问题描述】：

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

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

【问题讨论】：

将{@link ...} 转换为<a href="...">...</a> 的情况更糟。有关用例，请参阅correctly render javadoc method links to external html javadoc documents that use dashes instead of parentheses and commas。

标签： java javadoc escaping curly-braces

【解决方案1】：

尝试使用 HTML 转义：

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

【讨论】：

遗憾的是，这是最好的答案。
这很烦人，不是吗？我希望有更好的方法。
在 Eclipse Javadoc 视图中似乎没有正确呈现。
这真的按预期工作吗？文档说{@code} 中的内容不被解释为 HTML，就像 {@literal} 一样，因此有理由怀疑字符引用也不起作用。
我最终使用了 HTML 转义，没有 {@code} 标记。无论如何，它由 IDE 呈现为可读的。也使用<code></code> 会使标记更好。

【解决方案2】：

与其说是解决方法，不如说是一个答案，但如果您将{@code ...} 替换为旧版本的<code>...</code>，它将按照您的预期呈现花括号。

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

不幸的是，这会破坏尖括号，因此对于原始问题，您需要转义这些：

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

您甚至可以通过使用方便的 TextFX -> 转换 -> 编码 HTML (&") 让 Notepad++ 为您执行此操作来作弊。

这至少有一个好处，即在生成的 Javadoc 和 Eclipse 中的 Javadoc 视图中，一切都很好地呈现，这似乎不理解 &#125; 和朋友。

【讨论】：

【解决方案3】：

实际上我也遇到了同样的问题 - 没有一个命题对我有用（HTML 转义无论出于何种原因都不起作用）。如果这有帮助 - 尝试在有问题的符号之前关闭 {@code} 并在之后重新打开它，如下所示：

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

这似乎不是解决方案，但它有效，并且如果小心使用不会破坏格式:)

【讨论】：

啊，这个比我上面对arasul答案的投票要早。 arasul 仍然致力于充分利用 {@code} 和
```
 在 javadoc 和 cmets 中实现体面的 XML。
```

【解决方案4】：

bodunbodun 解决方案的工作原理通常是在 javadocs 中也有换行符。如果同时需要 { 和换行符，则 HTML 转义将不起作用

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

会给你

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

【讨论】：

当我想在我的评论中保留空格格式时获得我的投票，保留尖括号并显示 ${...} 就像在演示 maven 插件配置（属性）中一样。它使注释有点混乱，但有利于 javadoc 输出（和 eclipse javadoc 突出显示）。猜猜它是你更喜欢更漂亮的地方 - 评论或 javadoc - 尽管它有点不清晰。
遗憾的是，从 JDK 1.8 + Eclipse Neon 开始，严格的 javadoc 检查器会抱怨缺少 @code 的右大括号。所以我再次使用<pre><code/></pre>。

【解决方案5】：

至少从 Java 1.8.0_31 开始，我无法再重现该问题。您的输入按预期呈现：

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

我的测试表明javadoc 考虑了@code 内部的平衡花括号，并且仅在找到相应的花括号时才结束。

因此，如果代码像您的示例一样具有平衡的大括号 {}，它现在可以按预期工作。

但我仍然不知道如何处理不平衡的花括号，例如：

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

此外，行为取决于您使用的内联标签。 man javadoc 明确表示对于 @link：

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

所以在那种情况下不可能做得更好。

很遗憾，我找不到支持我实验的 @code 的类似报价。

【讨论】：

【解决方案6】：

使用{@literal}，所以这样做{@literal } }。在我的测试中有效。

所以对于你的情况，它看起来像这样：

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

【讨论】：

显然我的测试还不够。它与块中的尖括号不匹配。
它对我根本不起作用。第一个 } 关闭 @literal 之前的 {。

【解决方案7】：

为此找到了另一个不太出色的解决方法。它比其他的更好还是更差？我让你决定。将{@code } 部分替换为<code> </code>。（由于尖括号，这一切都消失了。）将第一个&lt; 包裹在{@literal } 中，使其看起来像{@literal<}。现在一切都会好起来的，而且在代码中并没有太可怕地被宰杀。最终结果是这样的

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

或者，如果您不喜欢{@literal<}，则可以改用&lt;。结果如下所示：

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

两者都不是很好的解决方案，但它们确实有效。

【讨论】：