JSDoc @param与@deprecated一起使用

Question

我有一个JavaScript函数获取一些参数,包括对象类型.但是,参数的一个属性(即对象)将被用作已弃用的属性.我想在文档中说明这种情况,但是我不知道如何在@deprecated中使用@param标签.考虑以下示例:

/**
* 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
}

我想弃用"options"对象的"type"属性.我怎么能这样做,或者我可以吗？

Answer 1

一个建议是使用打字稿，如下所示：

function test(
  options: {
    /**
     * @deprecated use newName instead
     */
    name?: string,
    newName?: string
  }) {
}

Answer 2

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')
  }
}