web-dev-qa-db-ja.com

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を使用してそのような戻り値を文書化する方法は？

javascriptnode.jsdocumentationjsdocpromise
66
Arikon

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> */でも動作します。

52
jillro

私は約束の外部型を定義する傾向があります：

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

JSDocでは、@typedefを使用してカスタムタイプを作成することもできます。これをかなり使用するので、文字列または配列であるprops/paramsは型の説明にリンクします（stringのように、文字列に使用できるネイティブを含むtypedefを作成しました（以下のJSDocの例を参照）。これは、@ propertyのように戻り値にオブジェクトのドット表記を使用して、戻り値の内容を示すことができないためです。 、そのタイプの定義（ '@typedef MyObject）を作成してから@returns {myObject} Definition of myObjectを作成できます。

ただし、型はできるだけリテラルにする必要があり、型を汚染したくないため、これに夢中になることはありませんが、型を明示的に定義したい場合があるので、その中に（Modernizrが良い例です...オブジェクトを返しますが、ドキュメントはありませんので、その戻り値の詳細を記述するカスタムtypedefを作成します）。

そのルートに行く必要がない場合は、既に述べたように、パイプ|を使用して、@ 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
*/
6
shadowstorm

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

3
holmberd

mightかもしれませんが[〜＃〜] deprecated [〜＃〜]。 mightに重点を置いているのは、 someone が非推奨（その回答へのコメントを確認）であると言う一方で、 others どちらかがいいと言います。とにかく完全性のために報告しています。

次に、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};
};
3
Francesco Casula

これが私がやりたいことです（少しやり過ぎかもしれません）：

/**
 * @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の1つにリンクしています）、プロミスが解決または失敗したときに呼び出されるコールバックを定義してから、コールバックのドキュメント。

最後に、特定のpromiseタイプを戻りタイプとして使用します。

0
niltz