CODEWITHSUNDEEP
javascriptcommentsjsdoc
Sam
Sam

Reputation: 1000

JSDoc comment within a JSDoc comment

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?

Upvotes: 4

Views: 1555

Answers (2)

dharcourt
dharcourt

Reputation: 963

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.

Upvotes: 1

SGD
SGD

Reputation: 1716

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.

Upvotes: 2

Related Questions