JSDoc文档中是否有官方的标签顺序？

Question

我正在记录一个JavaScript API。我遵循Google的样式指南，但我发现没有关于标签顺序的内容。

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

/**
 * @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;

尽管标签有一个明确定义的顺序（按字母顺序），但我觉得这有点令人困惑，因为它会干扰评论的自然顺序。这就是为什么我正在寻找一种用特定正式顺序编写标签的方法。

这些标签是否有官方顺序？

谢谢

- joaorodr84

Answer 1

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

总的来说，JSDoc并不关心标签的顺序，但有几个值得注意的例外：

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

- Jeff Williams

---

嗨，@Jeff Williams。感谢您的回答。我通常不使用描述标签。我像你说的那样，在开头写下描述而没有任何标签。至于参数顺序，我通常按顺序编写它们，但我不知道这是一个规则。所以，感谢您提供的信息。 :) - joaorodr84