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 décrire la structure de l'objet paramètres? Par exemple, cela devrait être quelque chose comme:

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

Depuis la page wiki @param :

Paramètres avec propriétés

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

 /**
  * @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 y avait autrefois une balise @config qui suivait immédiatement le @param correspondant, mais elle semble avoir été déconseillée ( exemple ici ).

À l'heure actuelle, il existe 4 façons différentes de documenter les 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 avec 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 qui ne sont utilisés que comme paramètres pour cette fonction et ne nécessitent pas de description supplémentaire de chaque propriété. Il peut être utilisé pour @returnsaussi bien .

Pour les objets avec un ensemble de propriétés connu (Variante B)

Les paramètres avec la syntaxe des propriétés sont très utiles :

/**
 * @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 qui ne sont utilisés que comme paramètres pour cette fonction et qui nécessitent une description plus détaillée de chaque propriété. Cela ne peut pas être utilisé pour @returns.

Pour les objets qui seront utilisés à plus d'un point dans la source

Dans ce cas, un @typedef est très pratique. Vous pouvez définir le type à un moment de votre source et l'utiliser comme type pour @paramou @returnsou 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 @parambalise:

/**
 * @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 au moins seront toujours contraintes à une chaîne. Le deuxième type (nombre) est le type de la valeur; cela peut être de n'importe quel type. Cette syntaxe peut également être utilisée @returns.

Ressources

Des informations utiles sur la documentation des types peuvent être trouvées ici:

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

PS:

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

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

ou:

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

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

Tout d'abord, la documentation officielle de JSDoc 3 ne nous donne aucun exemple sur le @return pour 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 renvoie 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 renvoie un objet dont 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 Full 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éfinissez 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 || {}
        }
    }

Pour @returnl'utilisation des balises {{field1: Number, field2: String}}, voir: http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDoc

Si un paramètre doit avoir une propriété spécifique, vous pouvez documenter cette propriété en fournissant une balise @param supplémentaire. Par exemple, si un paramètre d'employé doit avoir des propriétés de nom et de service, vous pouvez le documenter comme suit:

/**
 * Assign the project to a list of employees.
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee's department.
 */
function(employees) {
    // ...
}

Si un paramètre est déstructuré sans nom explicite, vous pouvez donner à l'objet un nom approprié et documenter ses propriétés.

/**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function({ name, department }) {
    // ...
};

Source: JSDoc

Il y a une nouvelle @configbalise pour ces cas. Ils sont liés aux précédents @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
 */