Javascript 如何在JSDoc中指定承诺的解决方案和拒绝类型？

我有一些返回promise对象的代码，例如，为NodeJ使用库

var Q=require（'Q'）；
/**
*@返回？？？
*/
功能任务（err）{
返回err？Q.reject（新错误（'someerror'））：Q.resolve（'someresult'）；
}

---

如何使用JSDoc记录这样的返回值？

使用JSDoc，您还可以使用

@typedef

创建自定义类型。我经常使用它，所以作为字符串或数组的props/params链接到类型的描述（比如对于

string

我创建了一个typedef，其中包含可用于string的本地变量（参见下面的示例JSDoc）。您可以用同样的方式定义自定义类型。这是因为您不能像@property那样使用对象点表示法来表示返回中的内容。因此，在返回类似对象的内容的情况下，您可以为该类型创建定义（'

@typedef MyObject

），然后

@returns{MyObject}myObject的定义

不过，我不会对此发疯，因为类型应该尽可能是文字类型，并且您不想污染您的类型，但是在某些情况下，您需要显式定义类型，这样您就可以记录其中的内容（一个很好的例子是Modernizer…它返回一个对象，但您没有该对象的文档，所以创建一个自定义typedef，详细说明返回中的内容）

如果您不需要走这条路线，那么正如前面提到的，您可以使用管道

为任何@param、@property或@return指定多种类型

在您的情况下，您还应该记录一个

@throws

，因为您正在抛出一个

新错误

：

*@throws{error}在属性err未定义或不可用时抛出一个真正的新错误事件

//saved in a file named typedefs.jsdoc, that is in your jsdoc crawl path
/**
    * @typedef string
    * @author me
    * @description A string literal takes form in a sequence of any valid characters. The `string` type is not the same as `string object`.
    * @property {number} length The length of the string
    * @property {number} indexOf The occurence (number of characters in from the start of the string) where a specifc character occurs
    * @property {number} lastIndexOf The last occurence (number of characters in from the end of the string) where a specifc character occurs
    * @property {string|number} charAt Gives the character that occurs in a specific part of the string
    * @property {array} split Allows a string to be split on characters, such as `myString.split(' ')` will split the string into an array on blank spaces
    * @property {string} toLowerCase Transfer a string to be all lower case
    * @property {string} toUpperCase Transfer a string to be all upper case
    * @property {string} substring Used to take a part of a string from a given range, such as `myString.substring(0,5)` will return the first 6 characters
    * @property {string} substr Simialr to `substring`, `substr` uses a starting point, and then the number of characters to continue the range. `mystring.substr(2,8)` will return the characters starting at character 2 and conitnuing on for 8 more characters
    * @example var myString = 'this is my string, there are many like it but this one is HOT!';
    * @example
    //This example uses the string object to create a string...this is almost never needed
    myString = new String('my string');
    myEasierString = 'my string';//exactly the same as what the line above is doing
*/

---

我倾向于为承诺定义一个外部类型：

/**
* A promise object provided by the q promise library.
* @external Promise
* @see {@link https://github.com/kriskowal/q/wiki/API-Reference}
*/

/**
* @return {external:Promise}  On success the promise will be resolved with 
* "some result".<br>
* On error the promise will be rejected with an {@link Error}.
*/
function task(err) {
    return err? Q.reject(new Error('Some error')) : Q.resolve('Some result');
}

现在，您可以在函数文档的

@return

语句中描述promise发生了什么变化：

/**
* A promise object provided by the q promise library.
* @external Promise
* @see {@link https://github.com/kriskowal/q/wiki/API-Reference}
*/

/**
* @return {external:Promise}  On success the promise will be resolved with 
* "some result".<br>
* On error the promise will be rejected with an {@link Error}.
*/
function task(err) {
    return err? Q.reject(new Error('Some error')) : Q.resolve('Some result');
}

/**
*@return{external:Promise}成功后，承诺将与
*“一些结果”。

*错误时，承诺将被拒绝，并出现{@link error}。
*/
功能任务（err）{
返回err？Q.reject（新错误（'someerror'））：Q.resolve（'someresult'）；
}

以下是我喜欢做的事情（可能有点过头了）：

基本上，使用指向某些文档的链接来定义基本承诺（在本例中，我链接到jQuery），定义承诺解析或失败时将调用的回调，然后定义链接回回调文档的特定承诺

---

最后，使用您的特定承诺类型作为返回类型。

即使它们在Javascript中不存在，我发现JSdoc理解“泛型类型”

因此，您可以定义自定义类型，然后使用

/*@return Promise*/

→ {Promise.}带有指向自定义

令牌的链接，请在文档中键入

/**
 * @typedef Token
 * @property {bool} valid True if the token is valid.
 * @property {string} id The user id bound to the token.
 */

/**
 * Consume a token
 * @param  {string} token [description]
 * @return {Promise<Token>} A promise to the token.
 */
TokenConsume = function (string) {
  // bla bla
}

/**
*@typedef令牌
*@property{bool}如果令牌有效，则为True。
*@property{string}id绑定到令牌的用户id。
*/
/**
*消费代币
*@param{string}标记[说明]
*@return{Promise}对令牌的承诺。
*/
TokenConsume=函数（字符串）{
//布拉布拉
}

它甚至适用于
/*@return Promise*/
或
/*@return Promise*/
还有另一种方法，即使它可能已弃用。强调可能，因为它表示已弃用（请查看对该答案的评论）尽管我说其中任何一个都可以，但为了完整起见，我还是要报告它

现在，以
Promise.all（）
为例，它返回一个用数组实现的承诺。使用点符号样式，它将如下所示：

{Promise.<Array.<*>>}

当我让PhpStorm生成文档时，我得到以下结果：

/**
 * @returns {Promise.<{array1: Array, array2: Array}>}
 */
const test = async () => {
    let array1 = [], array2 = [];

    return {array1, array2};
};

/**
*@returns{Promise.}
*/
常量测试=异步（）=>{
设array1=[]，array2=[]；
返回{array1，array2}；
};
Jsdoc3当前支持的语法：

/**
 * Retrieve the user's favorite color.
 *
 * @returns {Promise<string>} A promise that contains the user's favorite color
 * when fulfilled.
 */
User.prototype.getFavoriteColor = function() {
     // ...
};

参见github讨论：
我想知道一些类似的东西。如何记录一个函数的返回类型，该函数可以根据应用程序的输入和状态返回多个不同的东西？使用语法：@returns{*}通配符语法没有那么具体，也没有帮助。@arikon没有
@returns{ErrorObject | ResultObject}
help？使用“管道”登录类型描述是一种常见做法。@john doe不，它不是。因为函数返回的是Promise对象，而不仅仅是结果或错误。遗憾的是，这在PHPStorm中不起作用，PHPStorm会将
@typedef
标记中的类型突出显示为未解析。是的，duh，我在这里定义它！我没有抛出错误，只是创建它的实例来传递是的，这是一个想法！对于YUIDoc，我发现它是有效的：
@return{Promise | Token}
好主意！我把它修改为：
@returns{Promise | Promise | Error}
我非常不喜欢这个解决方案，因为jsdoc将typedef分离到一个与返回它的函数不同的页面上。它还要求您命名所有可解析的对象类型，但您真正想做的就是返回多个值并将它们包装到一个对象中。请从项目所有者处更新当前解决方案以及pl是什么anned for release刚刚发现了相同的东西。链接到上面从项目所有者处引用的注释
/**
 * A promise for the user's favorite color.
 *
 * @promise FavoriteColorPromise
 * @fulfill {string} The user's favorite color.
 * @reject {TypeError} The user's favorite color is an invalid type.
 * @reject {MissingColorError} The user has not specified a favorite color.
 */

/**
 * Retrieve the user's favorite color.
 *
 * @returns {FavoriteColorPromise} A promise for the user's favorite color.
 */
User.prototype.getFavoriteColor = function() {
    // ...
};