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 @.
