Is there an official order for JSDoc tags in documentation?

Question

i am documenting a JavaScript API. I am following the google style guide but I found nothing about the order of the tags.

I usually document a variable like this:

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

As you can see, I write the tags using my own order, the one I find the most intuitive.

Here is the same documentation with the tags ordered alphabetically:

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

Despite, having a well defined order (alphabetically), I find this is a bit confusing, because it messes up with the natural order of the comments. That is why I am looking for a way to write the tags with a specific official order.

Is there even an official order for these tags?

Thanks

Reprobation

Answer 1

There's no official order for JSDoc tags. I tend to put more general tags first, followed by more specific tags, similar to your first example.

In general, JSDoc doesn't care about the tag order, but there are a few notable exceptions:

• Any text before the first tag will be used as the description. You can also provide a description with the @desc (or @description) tag, as you did in your example.
• When you use the @param tag to document function parameters, the parameters must use the same order as the function signature.

Reactor

Hi @Jeff Williams. Thank you for your answer. I usually don't use the description tag. I do like you said, I just write the description at the beginning without any tag. As for the param order, I normally write them in order but I didn't know it was a rule. So, thank for the information you provided. :) – Reprobation