استفاده از @ و /* در کامنت‌های چندخطی

چجوری مشکل عدم امکان استفاده از علامت‌های خاص و رزرو‌ شده رو در کامنت‌های چندخطی (multiline comments) و JSDoc حل کنیم؟

در حال اضافه کردن کامنت JSDoc به کدهام بودم که به یه مشکل اعصاب خوردن‌کن برخوردم. وقتی داشتم یک تیکه کد مثال رو توی کامنتم اضافه میکردم که داخلش از علامت /* استفاده میشد، کل بلوک کامنتم خراب میشد. دلیلش هم اینه که این علامت در جاوااسکریپت به عنوان تگ پایان کامنت‌های چندخطی استفاده میشه و وقتی داخل خود کامنت میخوای ازش استفاده کنی جاوااسکریپت فکر میکنه که داری بلوک کامنتت رو میبندی!

این مشکل توی تیکه کد پایین قابل مشاهده‌است:

 1/**
 2 * Checks whether two permission strings are semantically equal or not.
 3 *
 4 * @example
 5 * // returns true
 6 * equals('a/b/c/d/allow', 'a/b/c/*⁣/*/d/allow');
 7 *
 8 * @returns {boolean} True in case of equality and false otherwise.
 9*/
10const equals = (first: string, second: string) => {
11    // function's logic
12    // ...
13
14    return true; // or false
15}

این مشکل راه حل ساده و جالبی داره: باید یه کاراکتر جداکننده‌ی مخفی بین * و / قرار داده بشه! این کاراکتر یونیکد که اسمش هست Unicode invisible separator character باعث میشه که جاوااسکریپت علامت پایان کامنت رو تشخیص نده. این کاراکتر رو میتونید از اینجا کپی کنید.

دقیقا مشابه همین مشکل وقتی به وجود میاد که بخواید از علامت @ داخل کامنت‌های JSDoc استفاده کنید. چون این علامت معنی خاصی برای JSDoc داره باعث خراب شدن داکیومنتی میشه که JSDoc تولید میکنه. به این تیکه کد یه نگاه بندازید:

 1/**
 2 * A NestJS handler decorator that defines an access permission constraint and enforces it.
 3 *
 4 * @example
 5 * `⁣`⁣`ts
 6 * // the request only needs to be authenticated and doesn't need any specific permissions
 7 * @RequiresAccess()
 8 * Class MyController {}
 9 * `⁣`⁣`
10 */
11export const RequiresAccess = Reflector.createDecorator<
12  PermissionPathGen | PermissionPathGen[]
13>({
14  transform(value) {
15    return value == undefined ? MUST_BE_AUTHENTICATED : value
16  },
17})

حل این مشکل هم مشابه قبلیه؛ کافیه یه کاراکتر جداکننده‌ی مخفی قبل از علامت @ قرار بدید.

منبع: Using @ and */ symbols inside JS multiline comments از وبلاگ Software Alchemist