JSDoc에서 약속의 해결 및 거부 유형을 지정하는 방법은 무엇입니까?

예를 들어 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> */.

약속에 대한 외부 유형을 정의하는 경향이 있습니다.

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

이제 프로 @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');
}

JSDoc을 사용하면 @typedef. 문자열 또는 배열 인 props / params가 유형의 설명에 연결되므로 이것을 꽤 많이 사용 string합니다 (예 : 문자열에 사용할 수있는 네이티브를 포함하는 typedef를 만든 경우 (아래의 JSDoc 예제 참조)). 사용자 정의 유형을 정의 할 수 있습니다. 이는 @property가 반환 내용을 나타내는 것처럼 반환에 객체 점 표기법을 사용할 수 없기 때문입니다. 따라서 객체와 같은 것을 반환하는 경우 정의를 만들 수 있습니다. 해당 유형 ( ' @typedef MyObject) 및 @returns {myObject} Definition of myObject.

하지만 타입은 가능한 한 리터럴이어야하고 타입을 오염시키고 싶지 않기 때문에 나는 이것에 미쳐 가지 않을 것입니다.하지만 타입을 명시 적으로 정의하고 싶은 경우가 있습니다. (좋은 예는 Modernizr입니다 ... 객체를 반환하지만 문서가 없으므로 해당 반환 내용을 자세히 설명하는 사용자 정의 typedef를 만듭니다).

해당 경로로 이동할 필요가 없다면 이미 언급했듯이 pipe를 사용하여 @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 토론을 참조하십시오.

DEPRECATED 일 수 있지만이를 수행하는 다른 방법도 있습니다 . 누군가 가 더 이상 사용되지 않는다고 말하고 (해당 답변에 대한 의견을 확인하십시오) 다른 사람들 은 어느 쪽이든 괜찮다고 말하기 때문에 might를 강조 하십시오 . 나는 완전성을 위해 어쨌든 그것을보고하고 있습니다.

이제 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;
}

기본적으로 일부 문서에 대한 링크를 사용하여 기본 약속을 정의하고 (이 경우에는 jQuery 하나에 연결합니다), 약속이 해결되거나 실패 할 때 호출 될 콜백을 정의한 다음 다시 연결되는 특정 약속을 정의합니다. 콜백 문서.

마지막으로 특정 약속 유형을 반환 유형으로 사용합니다.