在JSDoc中记录对象/函数变更的正确方式是什么？

Question

假设我有一个只接受一个参数的函数：

/**
 * @summary Some function.
 *
 * @since 1.0.0
 *
 * etc.
 */
function func( a ) {
   // do stuff...
}

随着几个版本的更新，现在已经支持第二个参数。在 PHPDoc 中，您可以添加额外的 @since 条目，以保持特定元素的更改日志：

/**
 * @summary Some function.
 *
 * @since 1.0.0
 * @since 1.2.0 Parameter b was added, because reasons.
 *
 * etc.
 */
function func( a, b ) {
   // do stuff...
}

这样做可以方便人们看到像这样的更改是何时引入的。在JSDoc中是否有“变更日志”标准元素？

我已经查看了usejsdoc.org上关于@since的页面，但没有提到类似的内容，也没有提到应该使用不同的标签。

- J.D.

Answer 1

离你提出问题已经有一段时间了，但现在有一个同名的标签：@since

（顺便说一句，如果你想为特定的方法加上版本号，可以使用@version。）

- Brett Zamir

---

我知道@since标记，但我想知道是否支持将其用于为单个元素创建具有多个@since条目的变更日志。 - J.D.

啊，抱歉。由于标签后面的签名只提到了“versionDescription”，我认为@since不适用，因为它只表示“类、方法或其他符号是在特定版本中添加的”，而不是参数。 - Brett Zamir