JSDoc Promise 多种解析类型

Question

我保证我会尝试使用 JSDoc 来记录。它具有三种解析类型，string[]、Object[] 和 Object。似乎有很多建议的方法来记录这一点，但我似乎找不到任何具体的东西。

https://github.com/jsdoc/jsdoc/issues/1197#issuecomment-312948746 似乎暗示这样的事情：

/**
 * The results of the DNS resolution request
 * @promise DNSResolve
 * @fufill {(string[]|Object[]|Object)}
 * @reject {Error}
 */

/**
 * Resolve a DNS record
 *
 * @returns {DNSResolve} The result
 */

注意：在这一篇中，我使用了此处建议的多种类型的答案 How do you document JSDoc with mixed parameter type?

但是，这似乎没有实现，也没有出现在 https://jsdoc.app/ 上。也显得很臃肿啰嗦

我的想法是遵循 TypeScripts return 类型的想法

Promise<string[] | Object[] | Object>

是否有关于如何执行此操作的任何类型的标准，或者我应该只使用问题 #1197 中建议的方案

Answer 1

您链接的主题包含您需要的所有答案。如果您也发现第一种方法 long-winded，请使用简写承诺 return 输入：

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

那是因为jsdoc.app非常，非常过时了。我也注意到了这一点，因为许多更新的 short-hand JSDoc shorthand 语法在网站上不是最新的，但在 IDE 中工作正常VSCode 和 Webstorm。

例如，@typedef 文档没有提到有一个像 /** @typedef {{ id: number, name: string }} */

这样的 shorthand 版本

它看起来“臃肿”，因为它是完整形式的版本，如果您需要为其所有部分添加描述，或者如果您需要记录拒绝类型（简写版本不支持），它非常适合).如果您不需要它，您应该使用简写版本。

此外，请记住 https://jsdoc.app/ is maintained by the same repository/developer as https://github.com/jsdoc/jsdoc ，与您链接的问题中的相同回购协议。因此，在该问题线程上所说的任何内容都应被视为事实。

Is there any kind of standard on how to do this or should I just use the scheme suggested by issue #1197

简写和完整语法都应该被认为是标准的，没有一个比另一个更好。使用适合您需要的任何一个。适合工作的适合工具。

JSDoc Promise 多种解析类型

JSDoc Promise multiple resolve types

javascript

jsdoc

jsdoc3