文档中是否有 JSDoc 标签的官方命令？

Question

我正在记录一个 JavaScript API。我正在关注谷歌风格指南，但我没有发现任何关于标签的顺序。

我通常这样记录一个变量：

/**
 * @description Radius of the circle
 * @private
 * @memberOf Circle
 * @type {Number}
 * @default
 */
Circle.prototype._radius = 1;

如您所见，我使用自己的顺序编写标签，这是我认为最直观的顺序。

这是相同的文档，标签按字母顺序排列：

/**
 * @default
 * @description Radius of the circle
 * @memberOf Circle
 * @private
 * @type {Number}
 */
Circle.prototype._radius = 1;

尽管有明确定义的顺序（按字母顺序），但我觉得这有点令人困惑，因为它与 cmets 的自然顺序相混淆。这就是为什么我正在寻找一种方法来编写带有特定官方命令的标签。

这些标签还有官方订单吗？

谢谢

Answer 1

JSDoc 标签没有正式的顺序。我倾向于先放置更通用的标签，然后是更具体的标签，类似于您的第一个示例。

一般来说，JSDoc 不关心标签顺序，但也有一些值得注意的例外：

• 第一个标签之前的任何文本都将用作描述。您还可以使用 @desc（或 @description）标签提供描述，就像您在示例中所做的那样。
• 当您使用@param标签记录函数参数时，参数必须使用与函数签名相同的顺序。