Using @ and */ symbols inside JS multiline comments

Photo by Luca Bravo on Unsplash

Using @ and */ symbols inside JS multiline comments

How to solve the problem of not being able to use reserved symbols of JS and JSDoc in multiline comments

While documenting JavaScript code using JSDoc, I stumbled upon an annoying issue. My attempts to include the /* symbol in the example code within a multiline comment caused the entire comment block to break. This happens because */ is recognized as the ending tag for a multiline comment in JavaScript.

You can see the problem clearly in the blow code block!

/**
 * Checks whether two permission strings are semantically equal or not.
 *
 * @example
 * // returns true
 * equals('a/b/c/d/allow', 'a/b/c/*⁣/*/d/allow');
 *
 * @returns {boolean} True in case of equality and false otherwise.
*/
const equals = (first: string, second: string) => {
    // function's logic
    // ...

    return true; // or false
}

The solution is surprisingly simple: insert a Unicode invisible separator character between * and /. This character acts as a stealthy spacer, preventing the JavaScript interpreter from recognizing the sequence as the end of a comment. You can find and copy this invisible character here.

The same problem happens if you use the @ symbol to put a JSDoc code example of a decorator. Because the @ symbol has a special meaning for JSDoc, it leads to unintended changes in the rendered documentation. Consider this snippet:

/**
 * A NestJS handler decorator that defines an access permission constraint and enforces it.
 *
 * @example
 * `⁣`⁣`ts
 * // the request only needs to be authenticated and doesn't need any specific permissions
 * @RequiresAccess()
 * Class MyController {}
 * `⁣`⁣`
*/
export const RequiresAccess = Reflector.createDecorator<
  PermissionPathGen | PermissionPathGen[]
>({
  transform(value) {
    return value == undefined ? MUST_BE_AUTHENTICATED : value;
  },
});

Solving this is the same as the previous problem, you need to put an invisible separator before the @.