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

NodeJSにQライブラリを使用するなど、promiseオブジェクトを返すコードがいくつかあります。

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

私は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');
}

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

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

非推奨になる可能性がある場合でも、これを行う別の方法もあります。重視かもしれないので、誰かがいる間（その答えへのコメントを確認してください）、それは非推奨だと言う他はどちらか一方で結構ですと言います。とにかく完全を期すために報告します。

ここ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};
};

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

/**
 * @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を定義します。コールバックドキュメント。

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