Comment décrire les arguments «objet» dans jsdoc?


316
// 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)
}

Réponses:


428

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 ).


17
malheureusement, la balise de retour ne semble pas avoir un code.google.com/p/jsdoc-toolkit/wiki/TagReturns
Michael Bylstra

1
Dans cette réponse similaire, stackoverflow.com/a/14820610/3094399, ils ont également ajouté des options @param {Object} au début. Je suppose que cela pourrait être redondant.
pcatre du

Avez-vous un exemple avec les paramètres de déstructuration ES6? Dans mon cas, je n'ai pas le actionnom, j'écris `foo = ({arg1, arg2, arg2}) => {...}`. Edit: question ici stackoverflow.com/questions/36916790/…
Eric Burel

une idée comment documenter un membre d'objet qui est une option? Je veux dire que mon objet utilisateur doit avoir un nom d'utilisateur et peut avoir un nom complet. alors comment spécifier que le nom complet est facultatif
Yash Kumar Verma

167

À 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
 */

La variante 1 fonctionne-t-elle avec plusieurs types de propriété? Comme {{dir: A|B|C }}?
CMCDragonkai

Toute annotation de type devrait être possible ici, alors oui
Simon Zyx

Et pour les objets dont les clés sont générées dynamiquement? Comme{[myVariable]: string}
Frondor

135

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 || {}
          }
      }

Quelqu'un connaît-il un moyen de générer cela dans IntelliJ / Webstorm? Plus précisément, je parle de la troisième option - définir un type.
Erez Cohen

Veuillez développer. Voulez-vous avoir un raccourci clavier ou un raccourci dans IDE pour générer ces docu ou voulez-vous que votre IDE comprenne ces docu? Peut-être les deux?
vogdb

@vogdb pourriez-vous, s'il vous plaît, jeter un œil à ce problème? Je crois que ce cas d'utilisation n'est pas couvert par vos excellents exemples: stackoverflow.com/questions/53191739/…
Pavel Polyakov

@PavelPolyakov j'ai regardé. Je ne sais vraiment pas comment répondre à votre question. Je suis hors de JS depuis un moment. N'hésitez pas à modifier ma réponse si vous avez de nouvelles informations.
vogdb


2

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


0

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

1
Pouvez-vous pointer vers la documentation de la @configbalise? Je n'ai rien trouvé sur usejsdoc.org , et cette page suggère qu'elle @configest obsolète.
Dan Dascalescu

4
Je pense que @configc'est obsolète à ce stade. YUIDoc recommande d'utiliser à la @attributeplace.
Mike DeSimone
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.