JSDoc @param вместе с @deprecated

У меня есть функция JavaScript, получающая некоторые параметры, включая типы объектов. Однако одно свойство параметра, являющегося объектом, будет использоваться как устаревшее. Я хотел бы указать эту ситуацию в документации, однако я не знаю, как использовать тег @param с @deprecated. Рассмотрим приведенный ниже пример:

/**
* This function does something.
*
* @name myFunction
* @function
* @since 3.0
* @param {function} [onSuccess] success callback
* @param {function} [onFailure] failure callback
* @param {object} [options] options for function
* @param {string} [options.lang] display language
* @param {string} [options.type] type of sth
*/
this.myFunction= function (onSuccess, onFailure, options) {
 //do something
}

Я хочу обесценить свойство type для объекта "options". Как я могу это сделать, или я могу?

1 ответ

Официальная документация JSDoc не означает, что тег @deprecated можно использовать для того, чтобы отказаться от чего-либо другого, кроме целого символа.

Тег @deprecated может использоваться для документирования того, что, например, функция в целом устарела.

/**
 * @deprecated since version 2.0.0
 */
function old () {
}

Вы можете, конечно, как сказал @Droogans в комментариях, добавить что-то вроде deprecated: перед описанием @param. Если разработчик каким-то образом по-прежнему заканчивается использованием устаревшей функции, вы можете реализовать предупреждение о каких-либо ролях.

/**
 * @param {string=} bar - Deprecated: description
 */
function foo (bar) {
 if (bar) {
 console.warn('Parameter bar has been deprecated since 2.0.0')
 }
}

licensed under cc by-sa 3.0 with attribution.