English 中文(简体)
如何在JavaDocs中引用“*/”
原标题:
  • 时间:2009-03-10 19:09:24
  •  标签:

我需要在我的JavaDoc注释中包含*/。问题是这也是关闭注释的相同序列。正确的引用/转义方式是什么?

例子:

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

后续:看起来我可以使用/代替斜杠。唯一的缺点是在文本编辑器中直接查看代码时不太易读。

/**
 * Returns true if the specified string contains "*/".
 */
最佳回答

使用HTML转义。

那么在你的例子中:

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

"/"被转义为"/"字符。"

Javadoc应该将转义序列原封不动地插入其生成的HTML中,然后在浏览器中呈现为“*/”。

如果你想要非常小心,你可以转义两个字符:*/ 转换成 */

编辑:

Follow up: It appears I can use / for the slash. The only downside is that this isn t all that readable when view the code directly.

所以呢?重点不在于你的代码可读性,重点在于你的代码文档可读性。大部分Javadoc注释中都包含了复杂的HTML用于解释。C#等价物提供了完整的XML标签库。我曾经看过一些非常复杂的结构,让我告诉你。

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)
问题回答

没有人提到{@literal}。这是另外一种选择:

/**
 * Returns true if the specified string contains "*{@literal /}".
 */

不幸的是,您一次无法逃避*/。带有一些缺点,但这也可以解决:

唯一的缺点是在文本编辑器中直接查看代码时,这并不易读。

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

这是“正确”的解决方案,但出于可读性的原因,我可能会选择:

/**
 * Returns true if the string contains an asterisk followed by slash.
 */

使用实体

*/ 

在您的文档中,它将显示为 "*/"。

我偶然发现的另一种方法,仅为了完整起见:添加一些 HTML 标记,不会改变“*”和“/”之间的输出。

  /**
   * *<b/>/
   */

与HTML转义解决方案相比,这似乎是一个丑陋的Hack,但它在HTML输出中也产生了正确的结果。

我建议您在某个地方添加一行注释,说一些类似的话。

// *&#47; is html for */




相关问题
热门标签