如何在JSDoc中指定承诺的解析和拒绝类型?

I have some code that returns a promise object, e.g. using Q library for NodeJS.

我有一些代码可以返回一个promise对象，例如使用Q库来表示NodeJS。

var Q = require('q');

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

How to document such a return value using JSDoc?

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

6 个解决方案

#1

Even if they don't exist in Javascript, I found that JSdoc understands "generic types".

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

So you can define your custom types and then use /* @return Promise<MyType> */. The following result in a nice TokenConsume(token) → {Promise.<Token>} with a link to your custom Token type in the doc.

因此，您可以定义自定义类型，然后使用/* @return Promise */。下面的结果在一个很好的TokenConsume(令牌)→{承诺。 }，包含到doc中自定义令牌类型的链接。

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

It even works with /* @return Promise<MyType|Error> */ or /* @return Promise<MyType, Error> */.

它甚至可以使用/* @return Promise< type my| Error> */或/* @return Promise */。 ,>

#2

I tend to define an external type for the promise:

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

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

Now you can describe in the @return statement of your function documentation what happens to the promise:

现在，您可以在函数文档的@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');
}

#3

With JSDoc you can also create custom types using @typedef. I use this quite a bit so props/params that are strings or arrays link to a description of the type (like for string I created a typedef that includes the natives available to string (see the example JSDoc below). You can define a custom type in this same manner. This is because you can't use the object dot notation for returns like you can for @property to denote what is in the return. So in cases where you are returning something like an object, you can create a definition for that type ('@typedef MyObject) and then @returns {myObject} Definition of myObject.

使用JSDoc，您还可以使用@typedef创建自定义类型。我使用了这一点，所以作为字符串或数组的道具/params链接到类型的描述(类似于字符串I创建了一个包含可用的本地字符串的typedef(参见下面的示例JSDoc)。您可以以同样的方式定义自定义类型。这是因为您不能像@property那样使用对象点表示法来表示返回中的内容。因此，在返回某个对象的情况下，可以为该类型创建一个定义('@typedef MyObject)，然后@return {MyObject}定义MyObject。

I wouldn't go crazy with this, though, because types should be as literal as possible and you don't want to pollute your types, but there are cases where you want to define the type explicitly, and so you can document what is in it (a good example is Modernizr...it returns an object, but you have no documentation of it, so create a custom typedef that details what is in that return).

不过，我不会为此疯狂，因为类型应该尽可能地纯化，您不想污染您的类型，但是在某些情况下，您希望显式定义类型，因此您可以记录其中的内容(一个很好的例子是Modernizr……它返回一个对象，但是您没有它的文档，因此创建一个自定义的typedef来详细说明返回的内容)。

If you don't need to go that route, then as someone already mentioned, you can specify multiple types for any @param, @property, or @return by using the pipe |.

如果您不需要走那条路线，那么正如前面提到的，您可以使用管道|为任何@param、@property或@return指定多个类型。

In your case, you should also document an @throws because you are throwing a new error: * @throws {error} Throws a true new error event when the property err is undefined or not available.

在您的例子中，您还应该记录一个@throw，因为您正在抛出一个新的错误:* @throw {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
*/

#4

Syntax currently supported by Jsdoc3:

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

Supported in the future?

支持在未来?

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

See github discussion at: https://github.com/jsdoc3/jsdoc/issues/1197

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

#5

There's also another way of doing this even though it might be DEPRECATED. Emphasis on might since someone says it's deprecated (check the comments to that answer) while others say either one is fine. I'm reporting it anyway for the sake of completeness.

还有另一种方法可以做到这一点，即使它可能被弃用。强调might，因为有人说它是不赞成的(查看对这个答案的评论)，而其他人说任何一个都可以。为了完整性起见，我还是报告一下。

Now, take Promise.all() for example which returns a Promise fulfilled with an array. With the dot notation style it would look like shown below:

现在，以Promise.all()为例，它返回一个包含数组的承诺。点符号样式如下所示:

{Promise.<Array.<*>>}

It works on JetBrains products (e.g. PhpStorm, WebStorm) and it's also used in the jsforce docs.

它适用于JetBrains产品(例如PhpStorm、WebStorm)，在jsforce文档中也有使用。

At the time of writing when I try to auto-generate some docs with PHPStorm it defaults to this style even though I found poor reference to it.

在编写本文时，当我试图用PHPStorm自动生成一些文档时，它默认使用这种样式，尽管我发现对它的引用很差。

Anyway if you take the following function as an example:

不管怎样，如果你以下面的函数为例

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

    return {array1, array2};
};

When I let PhpStorm generate the docs I get this:

当我让PhpStorm生成文档时，我得到了:

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

    return {array1, array2};
};

#6

Here is what I like to do (which may be a little overdone):

这是我喜欢做的(可能有点过头了):

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

Basically, define the base promise with a link to some documentation (in this case I am linking to the jQuery one), define your callbacks that will be called when the promise either resolves or fails, then define your specific promise which links back to the callback documentation.

基本上，用一些文档的链接来定义基本承诺(在本例中，我是链接到jQuery文档的)，定义当承诺解决或失败时将调用的回调，然后定义返回回调文档的特定承诺。

Finally, use your specific promise type as the return type.

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

#1