如何在JSDoc中指定诺言的分辨率和拒绝类型？

我有一些代码返回一个Promise对象，例如使用Q库的NodeJS。

var Q = require('q');

/**
 * @returns ???
 */
function task(err) {
    return err? Q.reject(new Error('Some error')) : Q.resolve('Some result');
}

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

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

因此，您可以定义自定义类型，然后使用/* @return Promise<MyType> */。以下结果是一个不错的TokenConsume（token）→{Promise。<Token>}，并带有指向您Token在文档中的自定义类型的链接。

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

它甚至可以与/* @return Promise<MyType|Error> */或一起使用/* @return Promise<MyType, Error> */。

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

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

现在，您可以在@return功能文档的声明中描述诺言发生了什么：

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

使用JSDoc，您还可以使用创建自定义类型@typedef。我用了很多，所以作为字符串或数组的props / params链接到该类型的描述（就像string我创建的typedef包括可用于字符串的本机一样（请参见下面的示例JSDoc）。您可以定义一个自定义类型这是因为您不能在返回中使用对象点表示法，就像@property不能在返回中使用对象点表示法一样。因此，在返回对象之类的情况下，可以创建一个定义对于该类型（' @typedef MyObject），然后@returns {myObject} Definition of myObject。

但是，我不会为此感到疯狂，因为类型应该尽可能地字面化，并且您不想污染您的类型，但是在某些情况下，您需要显式定义类型，因此可以记录什么是在其中（一个很好的例子是Modernizr ...它返回一个对象，但是您没有该对象的文档，因此创建一个自定义typedef来详细说明该返回中的内容）。

如果您不需要走那条路线，那么正如已经提到的那样，您可以使用pipe为任何@param，@property或@return指定多种类型|。

在您的情况下，您还应该记录，@throws因为您将抛出new error：* @throws {error} Throws a true new error event when the property err is undefined or not available。

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

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() {
     // ...
};

将来有支持吗？

/**
 * 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() {
    // ...
};

参见github讨论：https : //github.com/jsdoc3/jsdoc/issues/1197

还有这样即使它的另一种方式可能会被弃用。强调可能是因为有人说它已被弃用（请查看该答案的评论），而其他人则说任何一个都可以。为了完整起见，我还是在报告。

现在，以Promise.all()返回一个满足数组的Promise为例。使用点符号样式时，如下所示：

{Promise.<Array.<*>>}

它适用于JetBrains产品（例如PhpStorm，WebStorm），并且还用于jsforce docs中。

在撰写本文时，当我尝试使用PHPStorm自动生成一些文档时，即使我发现对它的引用很少，它也默认为这种样式。

无论如何，以以下功能为例：

// NOTE: async functions always return a Promise
const test = async () => { 
    let array1 = [], array2 = [];

    return {array1, array2};
};

当我让PhpStorm生成文档时，我得到以下信息：

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

    return {array1, array2};
};

这是我想做的事情（可能有些过头了）：

/**
 * @external Promise
 * @see {@link http://api.jquery.com/Types/#Promise Promise}
 */

/**
 * This callback is called when the result is loaded.
 *
 * @callback SuccessCallback
 * @param {string} result - The result is loaded.
 */

/**
 * This callback is called when the result fails to load.
 *
 * @callback ErrorCallback
 * @param {Error} error - The error that occurred while loading the result.
 */

/**
 * Resolves with a {@link SuccessCallback}, fails with a {@link ErrorCallback}
 *
 * @typedef {external:Promise} LoadResultPromise
 */

/**
 * Loads the result
 *
 * @returns {LoadResultPromise} The promise that the result will load.
 */
function loadResult() {
    // do something
    return promise;
}

基本上，使用一些文档的链接定义基本promise（在这种情况下，我链接到jQuery），定义当promise解决或失败时将调用的回调，然后定义链接到回调文档。

最后，使用特定的Promise类型作为返回类型。