如何在JSDoc中指定承诺的parsing和拒绝types?

我有一些代码返回一个承诺对象,例如使用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理解“generics”。

所以你可以定义你的自定义types,然后使用/* @return Promise<MyType> */ 。 下面的结果是一个很好的TokenConsume(令牌)→{Promise。<Token>},它带有一个指向你的自定义Tokentypes的链接。

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

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

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

现在你可以在你的函数文档的@return语句中描述promise的情况:

 /** * @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创build自定义types。 我使用这个相当多的东西,所以道具/参数是string或数组链接到types的描述(如string我创build了一个typedef,其中包括可用于string的本机(见下面的示例JSDoc)您可以定义一个自定义因为你不能像@property一样使用对象点符号来表示返回值,所以在你返回类似对象的东西的时候,你可以创build一个该types的定义(' @typedef MyObject ),然后@returns {myObject} Definition of myObject

尽pipe如此,我不会为此而疯狂,因为types应该尽可能的符合字面意思,而且你不想污染你的types,但是有些情况下你想明确地定义types,所以你可以logging什么是(一个很好的例子是Modernizr …它返回一个对象,但是你没有它的文档,所以创build一个自定义的typedef来详细说明返回的内容)。

如果你不需要走这条路线,那么就像已经提到的那样,你可以通过使用pipe道指定多个@param,@property或@returntypes。 。

在你的情况下,你还应该logging一个@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 */ 

我相信接受的答案是缺less一个.Promise这个词之后。

Promise.all()为例,它返回另一个用数组实现的Promise:

 {Promise.<Array.<*>>} 

引用jsforce文档 Promise.all() 返回一个包含每个promise的履行值的数组的promise

不要相信jsforce? 然后相信JetBrains =)

尝试写这个代码,让PHPStormWebStorm为你创buildJSDoc:

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

现在让PHPStormWebStorm创buildJSDoc和tada!

 /** * @returns {Promise.<{array1: Array, array2: Array}>} */ const test = async () => { let array1 = [], array2 = []; return {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() { // ... }; 

未来支持?

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

请参阅https://github.com/jsdoc3/jsdoc/issues/1197上的; github讨论

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

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

基本上,定义基本承诺与链接到一些文档(在这种情况下,我链接到jQuery之一),定义您的callback将被调用,当承诺要么解决或失败,然后定义您的具体承诺链接回到callback文档。

最后,使用您的特定承诺types作为返回types。