I have a promise that I am trying to document using JSDoc. It has three resolve types, string[], Object[] and Object. There seems to be a number of ways suggested to document this but I can't seem to find anything concrete.
https://github.com/jsdoc/jsdoc/issues/1197#issuecomment-312948746 would seem to sugest something like this:
/**
* The results of the DNS resolution request
* @promise DNSResolve
* @fufill {(string[]|Object[]|Object)}
* @reject {Error}
*/
/**
* Resolve a DNS record
*
* @returns {DNSResolve} The result
*/
Note: In this one I am using the answer to multiple types as suggested here How do you document JSDoc with mixed parameter type?
However, this doesn't seem to have been implemented and doesn't appear on https://jsdoc.app/. It also seems very bloated and long winded.
My idea was to follow TypeScripts return type idea of
Promise<string[] | Object[] | Object>
Is there any kind of standard on how to do this or should I just use the scheme suggested by issue #1197
The thread you linked has all the answers you need. If you find the first approach too long-winded, use the short hand promise return type:
/**
* @returns {Promise<(string[]|object[]|object>}
*/
However, this doesn't seem to have been implemented and doesn't appear on https://jsdoc.app/. It also seems very bloated and long winded.
That's because jsdoc.app is very, very out of date. I've noticed this too, as a lot of newer short-hand JSDoc shorthand syntax for a lot of things aren't up to date on the site but work fine in IDE's like VSCode and Webstorm.
For example, the @typedef docs don't mention there's a shorthand version like /** @typedef {{ id: number, name: string }} */
It seems "bloated" because it's the full form version which is well suited if you need to add a description to all its parts, or if you need to document reject types (which the short hand version doesn't support). If you don't need that, the short hand version is what you should use.
Also, keep in mind https://jsdoc.app/ is maintained by the same repository/developer as https://github.com/jsdoc/jsdoc , the same repo from the issue you linked. So anything said on that issue thread should be considered as truth.
Is there any kind of standard on how to do this or should I just use the scheme suggested by issue #1197
Both the short hand and full syntax should be considered standard, and neither is better than the other. Use whichever fits your needs. Right tool for the right job.