Каким образом и зачем создаются подобные комментарии в коде?

Question

Часто вижу в коде какую-то функцию и над ней подобный комментарий:

/**
 * Hello
 * @param req
 * @param res
 * @return {*}
 */
function(req, res) {
   return res.send('Hello');
}

Это какой-то инструмент делает подобные вещи или что это?

Answer 1

Это синтаксис JSDoc - https://ru.wikipedia.org/wiki/JSDoc - пришедший из Javadoc. Он позволяет автоматически создавать документацию для скрипта и т.д.

Но в последнее время он используется как замена Typescript для контроля типов. Например, в VSCode можно в начале скрипта вставить //@ts-check, указывать типы для параметров функции и возвращаемого значения. Также можно указывать типы для объявляемых переменных. Встроенный линтер "Problems" будет выдавать сообщения в случае нарушения, объявленных вами, типов.

// @ts-check

/**
 * @function convertToNumber takes a string and converts it to a number or NaN
 * @param {string} string a string that is going to be a number
 * @return {number}
 */
function convertToNumber(string){
    return Number(string);
}

/**@type {number} */
let m = convertToNumber('3.0');  // No problem

/**@type {string} */
let str = convertToNumber('3.0'); // Type 'number' is not assignable to type 'string'.

/**@type {number} */
let num = convertToNumber(3.0); // Argument of type 'number' is not assignable to parameter of type 'string'.

Типы могут быть не только примитивными, но и экземплярами классов, например:

/**@type {HTMLElement} */
let div = document.querySelector('div'); // No problem

/**@type {HTMLElement} */
let divs = document.querySelectorAll('div'); // Type 'NodeListOf<HTMLDivElement>' is missing the following properties from type 'HTMLElement': accessKey, accessKeyLabel, autocapitalize, dir, and 273 more.

Можно определять собственные типы, которые можно применять с инструкциями @param или @type с помощью инструкции @typedef:

/**
 * @typedef {(number|string)} NumberLike
 */

/**
 * @param {NumberLike} strnum
 */
 function convertToNumberAnyway(strnum){
    return Number(strnum);
 }
/**@type {number} */
 let number1 = convertToNumberAnyway('.3'); // No problem

/**@type {number} */
let number2 = convertToNumberAnyway(.3); // No problem

/**@type {number} */
let number3 = convertToNumberAnyway(false); // Argument of type 'boolean' is not assignable to parameter of type 'NumberLike'.

Документация по JSDoc: https://jsdoc.app/

БЛОГ НА HUSL

Каким образом и зачем создаются подобные комментарии в коде?

Ответы (1 шт):