javascript - exports - ¿Cómo especificar la resolución y el tipo de rechazo de la promesa en JSDoc?

jsdoc return

Question

Tengo algún código que devuelve un objeto de promesa, por ejemplo, usando Q biblioteca Q para NodeJS.

var Q = require(''q'');

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

¿Cómo documentar dicho valor de retorno utilizando JSDoc?

Answer 1

Con JSDoc también puedes crear tipos personalizados usando @typedef . Lo uso bastante, así que los props / params que son cadenas o arrays enlazan con una descripción del tipo (como para string , creé un typedef que incluye los nativos disponibles para string (vea el ejemplo JSDoc a continuación). Puede definir una costumbre escriba de la misma manera. Esto se debe a que no puede usar la notación de puntos del objeto para las devoluciones como puede hacerlo para que @property denote lo que está en la devolución. Por lo tanto, en los casos en los que está devolviendo algo como un objeto, puede crear definición para ese tipo ('' @typedef MyObject ) y luego @returns {myObject} Definition of myObject .

Sin embargo, no me volvería loco con esto, porque los tipos deberían ser lo más literal posible y usted no quiere contaminar sus tipos, pero hay casos en los que desea definir el tipo explícitamente, y así puede documentar lo que es. en él (un buen ejemplo es Modernizr ... devuelve un objeto, pero no tiene documentación de él, así que cree un typedef personalizado que detalle lo que hay en esa declaración).

Si no necesita ir por esa ruta, entonces, como alguien ya lo ha mencionado, puede especificar múltiples tipos para cualquier @param, @property o @return usando la tubería | .

En su caso, también debe documentar un @throws porque está lanzando un 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
*/

Answer 2

Esto es lo que me gusta hacer (lo que puede ser un poco exagerado):

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

Básicamente, defina la promesa base con un enlace a alguna documentación (en este caso estoy enlazando con jQuery), defina sus devoluciones de llamada que se llamarán cuando la promesa se resuelva o falle, luego defina su promesa específica que se vincula de nuevo a documentación de devolución de llamada.

Finalmente, use su tipo de promesa específico como el tipo de devolución.

Answer 3

Incluso si no existen en Javascript, encontré que JSdoc entiende "tipos genéricos".

Así que puedes definir tus tipos personalizados y luego usar /* @return Promise<MyType> */ . El siguiente resultado es un bonito TokenConsume (token) → {Promise. <Token>} con un enlace a su tipo de Token personalizado en el documento.

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

Incluso funciona con /* @return Promise<MyType|Error> */ o /* @return Promise<MyType, Error> */ .

Answer 4

Sintaxis actualmente soportada por 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() {
     // ...
};

¿Apoyado en el futuro?

/**
 * 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() {
    // ...
};

Consulte la discusión de github en: https://github.com/jsdoc3/jsdoc/issues/1197

Answer 5

También hay otra forma de hacerlo, aunque podría ser DEPRECATED . Haga énfasis en el poder ya que someone dice que está en desuso (verifique los comentarios a esa respuesta), mientras que others dicen que cualquiera de los dos está bien. Lo estoy informando de todos modos por el bien de la integridad.

Ahora, tome Promise.all() por ejemplo, que devuelve una Promesa cumplida con una matriz. Con el estilo de notación de puntos se vería a continuación:

{Promise.<Array.<*>>}

Funciona en productos JetBrains (por ejemplo, PhpStorm, WebStorm) y también se usa en los documentos de jsforce .

En el momento de escribir esto, cuando intento generar automáticamente algunos documentos con PHPStorm , este estilo aparece de manera predeterminada, aunque encontré una referencia pobre a este.

De todos modos si tomas la siguiente función como ejemplo:

// NOTE: async functions always return a Promise
const test = async () => { 
    let array1 = [], array2 = [];

    return {array1, array2};
};

Cuando dejo que PhpStorm genere los documentos, obtengo esto:

/**
 * @returns {Promise.<{array1: Array, array2: Array}>}
 */
const test = async () => {
    let array1 = [], array2 = [];

    return {array1, array2};
};

Answer 6

Tiendo a definir un tipo externo para la promesa:

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

Ahora puede describir en la declaración @return de la documentación de su función lo que sucede con la promesa:

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