Как указать разрешение и тип отклонения обещания в JSDoc?

Ответ 1

Даже если они не существуют в Javascript, я обнаружил, что JSdoc понимает "общие типы".

Итак, вы можете определить свои пользовательские типы, а затем использовать /* @return Promise<MyType> */. Следующий результат в хорошем TokenConsume (токене) → {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> */.

Ответ 2

Я склонен определять внешний тип для обещания:

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

Ответ 3

С помощью JSDoc вы также можете создавать собственные типы с помощью @typedef. Я использую это довольно немного, поэтому реквизиты/параметры, которые являются строками или массивами, ссылаются на описание типа (например, для 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
*/

Ответ 4

Есть и другой способ сделать это, даже если он может быть DEPRECATED. Акцент на может, поскольку кто-то говорит, что он устарел (проверьте комментарии к этому ответу), а другие говорят, что один из них в порядке. Я сообщаю об этом в любом случае ради полноты.

Теперь возьмите 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};
};

Ответ 5

Синтаксис, поддерживаемый в настоящее время Jsdoc3:

/**
 * Retrieve the user favorite color.
 *
 * @returns {Promise<string>} A promise that contains the user favorite color
 * when fulfilled.
 */
User.prototype.getFavoriteColor = function() {
     // ...
};

Поддерживается в будущем?

/**
 * A promise for the user favorite color.
 *
 * @promise FavoriteColorPromise
 * @fulfill {string} The user favorite color.
 * @reject {TypeError} The user favorite color is an invalid type.
 * @reject {MissingColorError} The user has not specified a favorite color.
 */

/**
 * Retrieve the user favorite color.
 *
 * @returns {FavoriteColorPromise} A promise for the user favorite color.
 */
User.prototype.getFavoriteColor = function() {
    // ...
};

См. обсуждение github по адресу: https://github.com/jsdoc3/jsdoc/issues/1197

Ответ 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;
}

В принципе, определите базовое обещание со ссылкой на некоторую документацию (в этом случае я связываюсь с jQuery), определите свои обратные вызовы, которые будут вызваны, когда обещание будет разрешено или не выполнено, затем определите свое конкретное обещание, которое связывает вернуться к документации обратного вызова.

Наконец, используйте тип вашего обещания как тип возврата.