能否嵌套Javadoc？代码演示时的注释闭合冲突问题

问题 #

需要在Javadoc的代码示例中包含Javadoc注释时，内部注释的*/会被识别为外层Javadoc的结束标记，导致外层注释提前终止，无法完整展示示例代码。

错误示例场景 #

以下代码中，内层Javadoc的*/会直接结束外层注释，后续示例代码无法被正确解析：

/**
 * Sample是一个用于实现有趣功能的工具类。
 * 示例用法如下：
 * 
 * <pre>{@code
 * /**
 *  * 我们定义一个Example类
 *  */
 * class Example {
 *     /**
 *      * 这个方法实现某些功能
 *      */
 *     void foo() {
 *         // ...
 *     }
 * 
 *     /**
 *      * 这个方法实现其他功能
 *      */
 *     void bar() {
 *         // ...
 *     }
 * 
 *     /**
 *      * 在main方法中调用foo()和bar()来演示功能
 *      */
 *     public static void main(String[] args) {
 *         // ...
 *         foo();
 *         // ...
 *         bar();
 *         // ...
 *         // 关键步骤：
 *         Sample.baz();
 *         // ...
 *     }
 * }
 * }</pre>
 */
public class Sample {
    /**
     * Sample类的核心功能方法
     */
    static void baz() {
        // ...
    }
}

次优方案的问题 #

尝试转义*/为*\/时，转义符号会直接显示在生成的Javadoc中，破坏代码示例的美观性：

/**
 * 外层注释
 * <pre>{@code
 * /**
 *  * 内层注释
 *  *\/
 * }
 * </pre>
 */
public class Sample {
    public static void main(String[] args) {
        System.out.println("Hello, world!");
    }
}

生成的Javadoc显示效果：

外层注释

 /**
  * 内层注释
  *\/

正确解决方案 #

使用HTML实体/替换内部Javadoc结束标记中的/，既不会触发外层Javadoc的终止，生成的文档又会正常显示*/：

/**
 * Sample是一个用于实现有趣功能的工具类。
 * 示例用法如下：
 * 
 * <pre>{@code
 * /**
 *  * 我们定义一个Example类
 *  * *&#47;
 * class Example {
 *     /**
 *      * 这个方法实现某些功能
 *      * *&#47;
 *     void foo() {
 *         // ...
 *     }
 * 
 *     /**
 *      * 这个方法实现其他功能
 *      * *&#47;
 *     void bar() {
 *         // ...
 *     }
 * 
 *     /**
 *      * 在main方法中调用foo()和bar()来演示功能
 *      * *&#47;
 *     public static void main(String[] args) {
 *         // ...
 *         foo();
 *         // ...
 *         bar();
 *         // ...
 *         // 关键步骤：
 *         Sample.baz();
 *         // ...
 *     }
 * }
 * }</pre>
 */
public class Sample {
    /**
     * Sample类的核心功能方法
     */
    static void baz() {
        // ...
    }
}

生成的Javadoc中，*/会被渲染为标准的*/，同时外层Javadoc可以完整解析整个代码示例。

另一种可选方案是将内部的*/拆分为* /（中间加空格），但这种方式会导致代码示例出现多余空格，不符合编码规范，因此优先推荐使用HTML实体的方案。

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