如何在JavaDocs中引用“* /”

时间:2009-03-10 19:09:24

标签: java comments javadoc

我需要在我的JavaDoc评论中包含*/。问题是这也是关闭评论的顺序。引用/逃避这个的正确方法是什么?

示例:

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

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

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

6 个答案:

答案 0 :(得分:36)

使用HTML转义。

所以在你的例子中:

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

/以“/”字符转义。

Javadoc应该将未经过修改的转义序列插入到它生成的HTML中,并且应该在浏览器中呈现为“* /”。

如果你想要非常小心,你可以逃避两个角色:*/转换为*/

修改

  

跟进:似乎我可以使用/   为斜线。唯一的缺点是   这不是那么可读的时候   直接查看代码。

所以?重点不在于您的代码是否可读,关键是您的代码文档是可读的。大多数Javadoc评论都嵌入了复杂的HTML来进行解释。地狱,C#的等价物提供了一个完整的XML标签库。我在那里看到了一些相当错综复杂的结构,让我告诉你。

编辑2: 如果它太困扰你,你可能会嵌入一个解释编码的非javadoc内联注释:

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

答案 1 :(得分:8)

没人提到{@literal}。这是另一种方式:

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

很遗憾,您无法一次逃离*/。有一些缺点,这也解决了:

  
    

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

  

答案 2 :(得分:7)

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

这是'正确'的解决方案,但出于可读性的考虑,我可能会选择:

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

答案 3 :(得分:6)

使用实体

*/ 

在您的文档中,它将显示为“* /”

答案 4 :(得分:5)

我建议你在某处附近添加一行评论

// */ is html for */

答案 5 :(得分:4)

我偶然发现的另一种方式,只是为了完整性:添加一些HTML标记,它不会改变*和/之间的输出。

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

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