JSDoc @param 与@deprecated

Question

我有一个 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
}

我想弃用“选项”对象的“类型”属性。我怎样才能做到这一点，或者我可以吗？

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

Answer 2

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

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