web-dev-qa-db-de.com

Wie legen Sie die Auflösungs- und Ablehnungsart der Zusage in JSDoc fest?

Ich habe einen Code, der ein Versprechungsobjekt zurückgibt, z. Verwenden von Q library für NodeJS.

var Q = require('q');

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

Wie dokumentiert man einen solchen Rückgabewert mit JSDoc?

57
Arikon

Selbst wenn sie in Javascript nicht vorhanden sind, habe ich festgestellt, dass JSdoc "generische Typen" versteht.

Sie können also Ihre benutzerdefinierten Typen definieren und dann /* @return Promise<MyType> */ verwenden. Das folgende Ergebnis in einem Nice TokenConsume (Token) → {Promise. <Token>} mit einem Link zu Ihrem benutzerdefinierten Token-Typ in das Dokument.

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

Es funktioniert sogar mit /* @return Promise<MyType|Error> */ oder /* @return Promise<MyType, Error> */.

41
Guilro

Ich neige dazu, einen externen Typ für das Versprechen zu definieren:

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

Nun können Sie in der @return-Anweisung Ihrer Funktionsdokumentation beschreiben, was mit dem Versprechen geschieht:

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

Mit JSDoc können Sie auch benutzerdefinierte Typen mit @typedef erstellen. Ich benutze dies ziemlich oft, also Requisiten/Params, die Zeichenfolgen oder Arrays sind, eine Verknüpfung mit dem Typ (wie für string habe ich ein Typedef erstellt, das die für String verfügbaren Eingeborenen enthält (siehe Beispiel-JSDoc unten) Geben Sie auf die gleiche Art und Weise ein, da Sie die Objektpunktnotation nicht für Rückgaben verwenden können, wie Sie für @property angeben können, um anzugeben, was in der Rückgabe enthalten ist. Wenn Sie also etwas wie ein Objekt zurückgeben, können Sie ein Definition für diesen Typ ('@typedef MyObject) und dann @returns {myObject} Definition of myObject.

Ich würde nicht verrückt damit werden, weil Typen so wörtlich wie möglich sein sollten und Sie Ihre Typen nicht verschmutzen möchten, aber es gibt Fälle, in denen Sie den Typ explizit definieren möchten und so dokumentieren können, was ist In ihr (ein gutes Beispiel ist Modernizr ... es gibt ein Objekt zurück, aber Sie haben keine Dokumentation davon, also erstellen Sie ein benutzerdefiniertes Typedef, das detailliert beschreibt, was in dieser Rückgabe enthalten ist).

Wenn Sie diese Route nicht benötigen, können Sie, wie bereits erwähnt, mehrere Typen für @param, @property oder @return mithilfe der Pipe | angeben.

In Ihrem Fall sollten Sie auch einen @throws dokumentieren, da Sie einen new error: * @throws {error} Throws a true new error event when the property err is undefined or not available werfen.

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

Derzeit von Jsdoc3 unterstützte Syntax:

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

In Zukunft unterstützt?

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

Siehe Github-Diskussion unter: https://github.com/jsdoc3/jsdoc/issues/1197

3
holmberd

Es gibt auch eine andere Möglichkeit, dies zu tun, obwohl es könnte [~ # ~] veraltet ist [~ # ~] . Die Betonung auf könnte sein, da jemand sagt, dass es veraltet ist (überprüfen Sie die Kommentare zu dieser Antwort), während andere sagen, entweder ist alles in Ordnung. Ich melde es trotzdem der Vollständigkeit halber.

Nehmen wir zum Beispiel Promise.all(), das eine mit einem Array erfüllte Zusage zurückgibt. Mit dem Punktschreibstil würde es wie folgt aussehen:

{Promise.<Array.<*>>}

Es funktioniert mit JetBrains-Produkten (z. B. PhpStorm, WebStorm) und wird auch in jsforce docs verwendet.

Zum Zeitpunkt des Schreibens, als ich versuche, einige Dokumente mit PHPStorm automatisch zu generieren, wird standardmäßig dieser Stil verwendet, obwohl ich einen schlechten Verweis darauf gefunden habe.

Wie auch immer, wenn Sie die folgende Funktion als Beispiel nehmen:

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

    return {array1, array2};
};

Wenn ich PhpStorm die Dokumente generieren lasse, erhalte ich Folgendes:

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

    return {array1, array2};
};
3

Folgendes mache ich gerne (was vielleicht etwas übertrieben ist):

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

Definieren Sie im Grunde das Basisversprechen mit einem Link zu einigen Dokumentationen (in diesem Fall verlinke ich auf die jQuery-Dokumentation), definieren Sie Ihre Rückrufe, die aufgerufen werden, wenn das Versprechen entweder aufgelöst wird oder nicht, und definieren Sie dann Ihr spezifisches Versprechen, das auf den Link verweist Callback-Dokumentation.

Verwenden Sie schließlich Ihren spezifischen Zusagetyp als Rückgabetyp.

0
niltz