Using @ and */ symbols inside JS 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 @.