JSDoc @param 和 @deprecated答案

【问题标题】：JSDoc @param together with @deprecatedJSDoc @param 和 @deprecated
【发布时间】：2015-06-28 02:59:55
【问题描述】：

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

我想弃用“选项”对象的“类型”属性。我该怎么做，或者我可以吗？

【问题讨论】：

我将在参数描述前加上DEPRECATED: 。然后，如果用户触摸它，我会console.log。
您不能弃用参数或属性，但您应该像这样将@param 标记为可选@param {string=}
@Droogans 当然，可以以任何方式通知用户不推荐使用的参数。我只是想知道是否有标准化的方式。
@ThinkingMedia “可选”可能是一种向用户显示该参数不是强制性的方式，但似乎仍不符合“已弃用”的确切含义。还是谢谢。

标签： javascript deprecated jsdoc param

【解决方案1】：

Official JSDoc documentation 并不表示@deprecated 标记可用于弃用除整个符号之外的任何内容。

@deprecated 标签可用于记录例如一个函数作为一个整体已被弃用。

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

}

当然，正如@Droogans 在 cmets 中所说，您可以在 @param 描述前添加类似 deprecated: 的内容。如果开发人员以某种方式最终仍然使用已弃用的功能，您可以实施某种警告。

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

【讨论】：

【解决方案2】：

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

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

【讨论】：

我确定这被否决了，因为问题是关于 JSDoc，但这是我真正想要的。它将指示 TS 编译器将该属性标记为已弃用。
它会将属性标记为已弃用，但问题是关于标记参数。为了解决这个问题，它需要将整个选项对象标记为已弃用。