Is it possible to nest javadoc?

Question

I want to nest javadoc in order to demonstrate some code functionality. However, the end of the inner javadoc comment block ends the outer comment block too.

Sample use case

/**
 * Sample is a utility for doing interesting stuff.
 * For example, you might use it this way:
 * 
 * <pre>{@code
 * /**
 *  * We write an Example class
 *  */
 * class Example {
 *     /**
 *      * This function does something.
 *      */
 *     void foo() {
 *         // ...
 *     }
 * 
 *     /**
 *      * This one does something else
 *      */
 *     void bar() {
 *         // ...
 *     }
 * 
 *     /**
 *      * now I'm gonna demonstrate something by calling foo() and bar() in this main method
 *      */
 *     public static void main(String[] args) {
 *         // ...
 *         foo();
 *         // ...
 *         bar();
 *         // ...
 *         // and now the kicker:
 *         Sample.baz();
 *         // everyone stands up and claps
 *         // ...
 *     }
 * }
 * }</pre>
 */
public class Sample {
    /**
     * Really cool thing that Sample does
     */
    static void baz() {
        // ...
    }
}

subpar solution

So I could try escaping the offending closing tags, but that shows up in the javadoc which is pretty ugly.

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

yields

outer doc

 /**
  * inner doc
  *\/

Write your inner comments using one-line `// this is a comment` syntax. — RealSkeptic, Apr 23 '23 at 10:08
maybe the answers to [Multiple line code example in Javadoc comment](https://stackoverflow.com/q/541920/16320675) can help (different problem, but some ideas) || also check [JEP 413](https://openjdk.org/jeps/413), introducing `@snippet` (Java 18) — user16320675, Apr 23 '23 at 10:50
Looks like this will become a bit easier with JDK 21, see [JDK-8301294](https://bugs.openjdk.org/browse/JDK-8301294). The specification there explicitly mentions `*@/` as solution for writing `*/`, but it also mentions that this will not work for any tags which treat their content literally, such as `{@code ...}`. — Marcono1234, May 11 '23 at 18:51

score 2 · Accepted Answer · answered Apr 23 '23 at 12:36

I personally would remove {@code and would just use HTML entities where necessary:

/**
 * Sample is a utility for doing interesting stuff.
 * For example, you might use it this way:
 * 
 * <pre>
 * /**
 *  * We write an Example class
 *  *&#x2f;
 * class Example {
 *     /**
 *      * This function does something.
 *      *&#x2f;
 *     void foo() {
 *         // ...
 *     }
 * 
 *     /**
 *      * This one does something else
 *      *&#x2f;
 *     void bar() {
 *         // ...
 *     }
 * 
 *     /**
 *      * now I'm gonna demonstrate something by calling foo() and bar() in this main method
 *      *&#x2f;
 *     public static void main(String[] args) {
 *         // ...
 *         foo();
 *         // ...
 *         bar();
 *         // ...
 *         // and now the kicker:
 *         Sample.baz();
 *         // everyone stands up and claps
 *         // ...
 *     }
 * }
 * </pre>
 */

This will also require escaping @, <, >, and & as well, if they appear in your example javadoc. @ would be escaped as @, < is <, > is >, and & is &.

Is it possible to nest javadoc?

Sample use case

subpar solution

1 Answers1