JSDoc comment within a JSDoc comment

Question

I'm giving code examples with JSDoc comments which also contain JSDoc comments, how can I escape the nested JSDoc comment without breaking the outer comment?

I'm using Version 3.3.0-beta3

Example:

 /**
  * @example
  * /**
  *  * Description.
  *  * @alias ...
  *  * @extends ...
  *  * @constructor
  *  */
  * function Something() {
  *     ...
  * }
  * ...
  */
 function MyFun() {
 ...

The nested */ will of course break the comment. An extra space will prevent this * / or a *\/, which then - of course - shows up in the JSDoc doc, which I don't want.

Is there any way to escape this so the generated JSDoc will look like the proper code?

Answer 1

I'm not aware of a way to escape this but you could write a simple plugin which does

exports.handlers = {
    newDoclet : function(doclet) {
        if(doclet.example){
            doclet.example = doclet.example.replace(/*\//g,'*/');
        }
    }
};

Note that I have not tried this out but it should do the trick.

Answer 2

If you're willing to have your examples in Markdown code blocks instead of JSDoc @example blocks, you can enable the Markdown plugin as described here and use HTML character references to escape one or more of the problematic nested comment characters, as in the following:

/**
 * Example:
 *
 *     /**
 *      * Description.
 *      * @alias ...
 *      * @extends ...
 *      * @constructor
 *      */
 *     function Something() {
 *         ...
 *     }
 *     ...
 */
function MyFun() {
...

This has been tested to work with JSDoc 3.3.2.