javascript - JSDocでpromiseの解決と拒否のタイプを指定するにはどうすればよいですか？

Question

たとえば、NodeJS用のQライブラリを使用して、promiseオブジェクトを返すコードがあります。

var Q = require('q');

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

JSDocを使用してそのような戻り値を文書化する方法は？

Answer 1

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> */ます。

Answer 2

私はpromiseの外部タイプを定義する傾向があります：

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

Answer 3

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のディスカッションを参照してください

Answer 4

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}プロパティ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
*/

Answer 5

非推奨になる可能性がある場合でも、これを行う別の方法もあります。誰かがそれが非推奨であると言うので（その答えへのコメントをチェックしてください）、他の人がどちらかが大丈夫だと言うので、力を強調します。とにかく完全を期すために報告します。

ここで、Promise.all()たとえば、配列で満たされたPromiseを返すものを考えてみましょう。ドット表記スタイルでは、次のようになります。

{Promise.<Array.<*>>}

JetBrains製品（PhpStorm、WebStormなど）で動作し、jsforceドキュメントでも使用されます。

この記事を書いている時点で、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};
};

Answer 6

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

/**
 * @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タイプをreturnタイプとして使用します。