web-dev-qa-db-fra.com

Comment décrire les arguments "objet" dans jsdoc?

// My function does X and Y.
// @params {object} parameters An object containing the parameters
// @params {function} callback The callback function
function(parameters, callback) {
}

Mais comment puis-je décrire comment l’objet de paramètres doit être structuré? Par exemple, cela devrait être quelque chose comme:

{
  setting1 : 123, // (required, integer)
  setting2 : 'asdf' // (optional, string)
}
javascriptjsdoc
259
Andy Hin

Depuis le @ param wiki page :

Paramètres avec propriétés

Si un paramètre doit avoir une propriété particulière, vous pouvez le documenter immédiatement après la balise @param pour ce paramètre, comme suit:

 /**
  * @param userInfo Information about the user.
  * @param userInfo.name The name of the user.
  * @param userInfo.email The email of the user.
  */
 function logIn(userInfo) {
        doLogIn(userInfo.name, userInfo.email);
 }

Il existait un tag @config qui suivait immédiatement le @param correspondant, mais il semble avoir été déconseillé ( exemple ici ).

367
Jonny Buchanan

Je vois qu'il existe déjà une réponse à propos de la balise @return, mais je souhaite donner plus de détails à ce sujet.

Tout d’abord, la documentation officielle de JSDoc 3 ne nous donne aucun exemple concernant le @return d’un objet personnalisé. Veuillez consulter https://jsdoc.app/tags-returns.html . Voyons maintenant ce que nous pouvons faire jusqu’à ce qu’une norme apparaisse.

  • La fonction retourne un objet où les clés sont générées dynamiquement. Exemple: {1: 'Pete', 2: 'Mary', 3: 'John'}. Habituellement, nous parcourons cet objet à l'aide de for(var key in obj){...}.

    JSDoc possible selon https://google.github.io/styleguide/javascriptguide.xml#JsTypes

    /**
 * @return {Object.<number, string>}
 */
function getTmpObject() {
    var result = {}
    for (var i = 10; i >= 0; i--) {
        result[i * 3] = 'someValue' + i;
    }
    return result
}

  • La fonction retourne un objet où les clés sont des constantes connues. Exemple: {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}. Nous pouvons facilement accéder aux propriétés de cet objet: object.id.

    JSDoc possible selon https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4

    • Fake It.

      /**
 * Generate a point.
 *
 * @returns {Object} point - The point generated by the factory.
 * @returns {number} point.x - The x coordinate.
 * @returns {number} point.y - The y coordinate.
 */
var pointFactory = function (x, y) {
    return {
        x:x,
        y:y
    }
}

    • Le plein Monty.

      /**
 @class generatedPoint
 @private
 @type {Object}
 @property {number} x The x coordinate.
 @property {number} y The y coordinate.
 */
function generatedPoint(x, y) {
    return {
        x:x,
        y:y
    };
}

/**
 * Generate a point.
 *
 * @returns {generatedPoint} The point generated by the factory.
 */

var pointFactory = function (x, y) {
    return new generatedPoint(x, y);
}

    • Définir un type.

      /**
 @typedef generatedPoint
 @type {Object}
 @property {number} x The x coordinate.
 @property {number} y The y coordinate.
 */


/**
 * Generate a point.
 *
 * @returns {generatedPoint} The point generated by the factory.
 */

var pointFactory = function (x, y) {
    return {
        x:x,
        y:y
    }
}

    Selon https://google.github.io/styleguide/javascriptguide.xml#JsTypes

    • Le type d'enregistrement.

      /**
 * @return {{myNum: number, myObject}}
 * An anonymous type with the given type members.
 */
function getTmpObject() {
    return {
        myNum: 2,
        myObject: 0 || undefined || {}
    }
}
128
vogdb

A présent, il existe 4 manières différentes de documenter des objets en tant que paramètres/types. Chacun a ses propres utilisations. Cependant, seuls 3 d'entre eux peuvent être utilisés pour documenter les valeurs de retour.

Pour les objets ayant un ensemble de propriétés connu (variante A) 

/**
 * @param {{a: number, b: string, c}} myObj description
 */

Cette syntaxe est idéale pour les objets utilisés uniquement comme paramètres de cette fonction et ne nécessitant pas de description supplémentaire de chaque propriété. Il peut également être utilisé pour @returns .

Pour les objets ayant un ensemble de propriétés connu (variante B)

La syntaxe paramètres avec propriétés est très utile:

/**
 * @param {Object} myObj description
 * @param {number} myObj.a description
 * @param {string} myObj.b description
 * @param {} myObj.c description
 */

Cette syntaxe est idéale pour les objets utilisés uniquement comme paramètres de cette fonction et nécessitant une description plus détaillée de chaque propriété. Ceci ne peut pas être utilisé pour @returns.

Pour les objets qui seront utilisés à plusieurs reprises dans la source

Dans ce cas, un @ typedef est très utile. Vous pouvez définir le type en un point de votre source et l'utiliser comme type pour @param ou @returns ou d'autres balises JSDoc pouvant utiliser un type.

/**
 * @typedef {Object} Person
 * @property {string} name how the person is called
 * @property {number} age how many years the person lived
 */

Vous pouvez ensuite l'utiliser dans une balise @param:

/**
 * @param {Person} p - Description of p
 */

Ou dans un @returns:

/**
 * @returns {Person} Description
 */

Pour les objets dont les valeurs sont toutes du même type 

/**
 * @param {Object.<string, number>} dict
 */

Le premier type (chaîne) documente le type des clés qui en JavaScript est toujours une chaîne ou du moins seront toujours forcées à une chaîne. Le deuxième type (nombre) est le type de la valeur; cela peut être n'importe quel type. Cette syntaxe peut également être utilisée pour @returns.

Ressources

Des informations utiles sur les types de documentation peuvent être trouvées ici:

https://jsdoc.app/tags-type.html

PS:

pour documenter une valeur optionnelle, vous pouvez utiliser []:

/**
 * @param {number} [opt_number] this number is optional
 */

ou:

/**
 * @param {number|undefined} opt_number this number is optional
 */
108
Simon Zyx

Pour la balise @return, utilisez {{field1: Number, field2: String}}, voir: http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDoc

18
maliboo

Il existe une nouvelle balise @config pour ces cas. Ils sont liés au précédent @param.

/** My function does X and Y.
    @params {object} parameters An object containing the parameters
    @config {integer} setting1 A required setting.
    @config {string} [setting2] An optional setting.
    @params {MyClass~FuncCallback} callback The callback function
*/
function(parameters, callback) {
    // ...
};

/**
 * This callback is displayed as part of the MyClass class.
 * @callback MyClass~FuncCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */
2
Mike DeSimone