Javadoc 是否有与等效的内容？

发布于 2024-08-11 23:52:18 字数 479 浏览 10 评论 0原文

不幸的是，HTML 中没有 CDATA。

这很遗憾，因为它非常适合添加包含 XML 的 javadoc 注释，因此您不必转义 javadoc 注释。和 >，例如：

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

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

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

或者它可以使用一些比 CDATA 更简单的语法。由于 javadoc 是可扩展的，因此可能有人添加了此功能；或者也许javadoc已经把它埋在里面的某个地方......有人知道吗？

原文

Unfortunately, there is no CDATA in HTML.

This is a pity, because it would be perfect for adding javadoc comments that include XML, so you don't have to escape the < and >, for example:

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

However, it would be possible for javadoc to recognize the CDATA section, and convert it to HTML for you. For example:

This parses <complexType name="">

Or it could use some simpler syntax than CDATA. Because javadoc is extensible, it's possible someone has added this functionality; or maybe javadoc already has it buried somewhere inside... Does anybody know?

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

一袭水袖舞倾城 2024-08-18 23:52:18

您可以使用 JavaDoc 的 @code 标记： /** 这会解析 {@code} */

回复收藏 0 原文

谁的年少不轻狂 2024-08-18 23:52:18

扩展 @Fabian 的答案，我同时使用

 和 {@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>
 */

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

使用 Eclipse 3.6.1 进行测试。

Extending @Fabian's answer, I use both <pre> and {@code ...}. Here an example with XML as source code:

/*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> allows you to write code on multiple lines and preserve its structure.

Tested with Eclipse 3.6.1.

回复收藏 0 原文

撩动你心 2024-08-18 23:52:18

关闭并重新打开大括号周围的 {@code} 标记，以使 ${dollar_sign_variables} 在 Eclipse 中正确呈现，尽管错误 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>

Close and reopen the {@code} tag around the braces to get ${dollar_sign_variables} to render correctly in eclipse despite bug 206319 and bug 206345 and without resorting to full HTML escaping:

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

which renders in Eclipse Indigo SR2 (3.7.2) as

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

回复收藏 0 原文

独夜无伴 2024-08-18 23:52:18

我尝试了很多解决方案，但没有一个能够满足我的需求。使用 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 转义方法（你可以使用这个) 让它正确渲染：

这个：

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

渲染如下：

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

不幸的是，这会让你陷入一个你无法真正理解的境地除非您呈现 Javadoc，否则“示例 xml”将被记录。幸运的是 eclipse 可以即时为你做这件事......

I have tried quite a few solutions, none of which were very satisfactory for my needs. Doing the pre + @code (or @literal) tags will usually work:

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

The trouble is, what if you have ${dollar_sign_variables} in your html? (and this is frequent if your documentation uses xml examples which rely on maven filtering). Say you have ${ITEM_INDEX_TO_LOGICAL}, Eclipse will render it like this:

<configFiles>
  <configFile>
     ITEM_INDEX_TO_LOGICAL

   }

Ultimately, I had no choice but to stick to the html-escaping method (you can use this one) to get it to render propertly:

This:

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

Renders like this:

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

This will unfortunately put you into a position where you can't really understand the 'example xml' being documented unless you render the Javadoc. Fortunately eclipse can do this for you on the fly...

回复收藏 0 原文

~没有更多了~