如何引用“*/"在 JavaDocs 中 [英] How to quote "*/" in JavaDocs

问题描述

我需要在我的 JavaDoc 注释中包含 */.问题是这也是关闭评论的相同顺序.引用/转义这个的正确方法是什么?

I have a need to include */ in my JavaDoc comment. The problem is that this is also the same sequence for closing a comment. What the proper way to quote/escape this?

示例:

/**
 * Returns true if the specified string contains "*/".
 */
public boolean containsSpecialSequence(String str)

跟进:看来我可以使用 / 作为斜线.唯一的缺点是，直接在文本编辑器中查看代码时，这并不是那么易读.

Follow up: It appears I can use / for the slash. The only downside is that this isn't all that readable when viewing the code directly in a text editor.

/**
 * Returns true if the specified string contains "*/".
 */

推荐答案

使用 HTML 转义.

Use HTML escaping.

所以在你的例子中:

/**
 * Returns true if the specified string contains "*/".
 */
public boolean containsSpecialSequence(String str)

/ 转义为/"字符.

Javadoc 应该将未受干扰的转义序列插入到它生成的 HTML 中，并且应该在浏览器中呈现为*/".

Javadoc should insert the escaped sequence unmolested into the HTML it generates, and that should render as "*/" in your browser.

如果你想非常小心，你可以转义这两个字符:*/ 转换为 */

If you want to be very careful, you could escape both characters: */ translates to */

跟进:看来我可以使用 /对于斜线.唯一的缺点是这不是那么可读的时候直接查看代码.

所以?重点不在于您的代码是否可读，重点在于您的代码文档 是否可读.大多数 Javadoc 注释都嵌入了复杂的 HTML 以进行解释.地狱，C# 的等效项提供了一个完整的 XML 标记库.我在那里看到了一些非常复杂的结构，让我告诉你.

So? The point isn't for your code to be readable, the point is for your code documentation to be readable. Most Javadoc comments embed complex HTML for explaination. Hell, C#'s equivalent offers a complete XML tag library. I've seen some pretty intricate structures in there, let me tell you.

编辑 2:如果它太困扰您，您可以嵌入一个解释编码的非 javadoc 内联注释:

Edit 2: If it bothers you too much, you might embed a non-javadoc inline comment that explains the encoding:

/**
 * Returns true if the specified string contains "*/".
 */
// returns true if the specified string contains "*/"
public boolean containsSpecialSequence(String str)

这篇关于如何引用“*/"在 JavaDocs 中的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！