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
}

我想弃用“options”对象的“type”属性，我该怎么做？还是说我可以这样做吗？

- moztemur

---

我将在参数描述之前加上“DEPRECATED:”。如果用户触摸它，我将打印一些内容。 - yurisich

你不能废弃参数或属性，但是你应该将 @param 标记为可选的，就像这样 @param {string=}。 - Reactgular

@Droogans 当然，可以以任何方式通知用户有关已弃用参数的信息。我只是想知道是否有标准化的方法。 - moztemur

@ThinkingMedia "可选的" 可能是向用户展示参数不是必需的一种方式，但似乎仍然不符合“已弃用”的确切含义。无论如何，谢谢。 - moztemur

Answer 1

官方 JSDoc 文档 没有说明 @deprecated 标签仅可用于废弃整个符号，而不是其他任何内容。

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

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

}

当然，如评论中@Droogans所说，您可以在@param描述前面添加类似于deprecated:的内容。如果开发人员仍然使用已弃用的功能，则可以实现某种警告。

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

- user1878974

---

如果有类似于@deprecated(param)这样的东西就太酷了。 - kungfooman

Answer 2

一个建议是使用TypeScript，如下所示：

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

- aaron

---

我相信这个问题被 downvote 是因为它与 JSDoc 有关，但这确实是我正在寻找的答案。这将指示 TS 编译器将该属性标记为已弃用。 - Payton Swick

它会将属性标记为已弃用，但问题是关于标记参数的。为了遵循问题，需要将整个选项对象标记为已弃用。 - Darc

@Darc，是的，注释也适用于选项。 - aaron