Javadoc 是否具有 <![CDATA[ ... ]]> 的等价物？答案

【问题标题】：Does Javadoc have an equivalent to <![CDATA[ ... ]]>?Javadoc 是否具有 <![CDATA[ ... ]]> 的等价物？
【发布时间】：2010-12-19 10:00:12
【问题描述】：

很遗憾，HTML 中没有 CDATA。

这是一个遗憾，因为它非常适合添加包含 XML 的 javadoc cmets，因此您不必对进行转义，例如：

/**<![CDATA[ This parses <complexType name=""> ]]>*/

但是，javadoc 可以识别 CDATA 部分，并为您将其转换为 HTML。例如：

This parses &lt;complexType name=""&gt;

或者它可以使用比 CDATA 更简单的语法。因为javadoc 是可扩展的，所以可能有人添加了这个功能；或者javadoc 已经埋在里面了……有人知道吗？

【问题讨论】：

标签： java html xml javadoc cdata

【解决方案1】：

可以使用JavaDoc的@code标签：/** This parses {@code <complexType name="">} */

【讨论】：

+1 请注意，{@code ... } 可以跨越多行。 eclipse 会声称这是一个错误，但事实并非如此。它也做括号计数！因此，只要它们匹配，您就可以在实际代码 sn-p 中使用卷曲。
我看到 IDEA 通过将行折叠在一起来处理多行 {@code} 块，<pre> 不会受到影响。这很可悲，因为{@code} 听起来是一个很好的解决方案，不必逃避开头的插入符号。

【解决方案2】：

扩展@Fabian's answer，我同时使用<pre>和{@code ...}。这里以 XML 作为源代码的示例：

/*Outputs data from a result set to an XML
 * with following structure:
 * <pre>
 * {@code
 * <row>
 *  <FIELD1>gregh</FIELD1>
 *  <FIELD2>487</FIELD2>
 *  <!-- etc. -->
 * </row>
 * <!-- more rows-->
 * }
 * </pre>
 */

<pre> 允许您在多行上编写代码并保留其结构。

使用 Eclipse 3.6.1 测试。

【讨论】：

【解决方案3】：

我尝试了很多解决方案，但没有一个能满足我的需求。做pre + @code（或@literal）标签通常会起作用：

 <pre>
 {@literal
 <configFiles>
   <configFile>
     <type>LOGICAL_INDEX_CONFIG</type>
   </configFile>
 </configFiles>}
 </pre>

问题是，如果你的 html 中有 ${dollar_sign_variables} 怎么办？（如果您的文档使用依赖于 Maven 过滤的 xml 示例，这很常见）。假设你有 ${ITEM_INDEX_TO_LOGICAL}，Eclipse 会这样渲染它：

<configFiles>
  <configFile>
     ITEM_INDEX_TO_LOGICAL

   }

最终，我别无选择，只能坚持使用 html-escaping 方法（您可以使用 this one）让它正确呈现：

这个：

 &lt;configFiles&gt;
   &lt;configFile&gt;
     &lt;type&gt;${ITEM_INDEX_TO_LOGICAL}&lt;/type&gt;
   &lt;/configFile&gt;
 &lt;/configFiles&gt;

像这样渲染：

 </configFiles>
   <configFile>
     <type>${ITEM_INDEX_TO_LOGICAL}</type>
   </configFile>
 </configFiles>

不幸的是，这将使您无法真正理解所记录的“示例 xml”，除非您呈现 Javadoc。幸运的是，eclipse 可以即时为您执行此操作...

【讨论】：

【解决方案4】：

关闭并重新打开大括号周围的 {@code} 标记，以使 ${dollar_sign_variables} 在 Eclipse 中正确呈现，尽管有 bug 206319 和 bug 206345 并且不诉诸完整的 HTML 转义：

/*
 * <pre>
 * {@code
 * <outer>
 *   <inner1>Text</inner1>
 *   <inner2>$}{ "script" }{@code </inner2>
 * </outer>
 * }
 * </pre>
 */

在 Eclipse Indigo SR2 (3.7.2) 中呈现为

<outer>
  <inner1>Text</inner1>
  <inner2>${ "script" }</inner2>
</outer>

【讨论】：