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

Official JSDoc documentation并不表示@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
  }) {
}

JSDoc @param与@deprecated一起使用

2 个答案: