DEV Community

Cover image for Using @ and */ symbols inside JS multiline comments
Hamidreza Mahdavipanah
Hamidreza Mahdavipanah

Posted on • Originally published at hamidreza.tech on

1

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
}
Enter fullscreen mode Exit fullscreen mode

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;
  },
});
Enter fullscreen mode Exit fullscreen mode

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

Image of Docusign

Bring your solution into Docusign. Reach over 1.6M customers.

Docusign is now extensible. Overcome challenges with disconnected products and inaccessible data by bringing your solutions into Docusign and publishing to 1.6M customers in the App Center.

Learn more

Top comments (0)

A Workflow Copilot. Tailored to You.

Pieces.app image

Our desktop app, with its intelligent copilot, streamlines coding by generating snippets, extracting code from screenshots, and accelerating problem-solving.

Read the docs

👋 Kindness is contagious

Please leave a ❤️ or a friendly comment on this post if you found it helpful!

Okay