如何在Javadoc的<pre>代码块中正确转义/**和*/字符序列？

块中转义/*和/的正确方法 #

遇到这种Javadoc解析器误把代码里的注释标记当成文档注释边界的问题太常见了，我来给你几个靠谱的解决办法：

方法1：用{@literal}标签（最推荐） #

{@literal}是Javadoc专门用来原样显示内容的标签，它会告诉解析器不要处理里面的任何特殊标记，包括/*和/。直接把包含冲突字符的代码片段用它包裹起来就行：

/**
 * 代码示例：
 * <pre> // 这样调用foo：foo({@literal "/**/*/?.txt"}); </pre>
 * */
public void foo(String glob) { }

这样既不会触发Javadoc提前结束的编译错误，生成的文档里也会完美显示原始字符串，写法还简洁直观。

方法2：插入HTML空注释拆分冲突序列 #

如果不想用{@literal}，可以在冲突的*/中间插入一个HTML空注释<!-- -->，让Javadoc解析器识别不出这是注释结束标记：

/**
 * 代码示例：
 * <pre> // 这样调用foo：foo("/**/*<!-- -->/?.txt"); </pre>
 * */
public void foo(String glob) { }

生成的文档里看不到这个空注释，显示效果和原始字符串一致，就是写起来稍微麻烦一点。

方法3：使用HTML实体替换特殊字符 #

把*换成*，把/换成/，也能让解析器不识别注释标记：

/**
 * 代码示例：
 * <pre> // 这样调用foo：foo("/&#42;&#42;/*&#47;?.txt"); </pre>
 * */
public void foo(String glob) { }

这种方法的缺点是编写时可读性差，除非特殊情况不推荐用。

为什么你之前的尝试没成功？ #

• 用反斜杠转义：Javadoc不支持这种方式，反斜杠会被原样显示在生成的文档里，达不到转义效果。
• 直接用{@code}：Javadoc解析器会优先识别注释块的边界标记（/*和/），所以如果{@code}里直接写这些字符，解析器还是会误判，导致文档提前结束。如果一定要用{@code}，得把它嵌套在{@literal}里，不过这就多此一举了。

内容的提问来源于stack exchange，提问作者atamanroman