¿Cómo describir argumentos de "objeto" en 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) {
}

Pero, ¿cómo describo cómo deben estructurarse los objetos de parámetros? Por ejemplo, debería ser algo como:

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

Respuestas:


428

Desde la página wiki de @param :


Parámetros con propiedades

Si se espera que un parámetro tenga una propiedad particular, puede documentarlo inmediatamente después de la etiqueta @param para ese parámetro, así:

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

Solía ​​haber una etiqueta @config que seguía inmediatamente al @param correspondiente, pero parece que ha quedado en desuso ( ejemplo aquí ).


17
desafortunadamente, la etiqueta de devolución no parece tener un código
Michael Bylstra

1
En esta respuesta similar stackoverflow.com/a/14820610/3094399 también agregaron opciones @param {Object} al principio. Sin embargo, supongo que podría ser redundante.
pcatre

¿Tienes algún ejemplo con los parámetros de desestructuración de ES6? En mi caso no tengo el actionnombre, escribo `foo = ({arg1, arg2, arg2}) => {...}`. Editar: pregunta aquí stackoverflow.com/questions/36916790/…
Eric Burel

alguna idea de cómo documentar un miembro de objeto que es la opción? Quiero decir que mi objeto de usuario debe tener un nombre de usuario y puede tener un nombre completo. Entonces, ¿cómo especifico que el nombre completo es opcional
Yash Kumar Verma

167

Por ahora hay 4 formas diferentes de documentar objetos como parámetros / tipos. Cada uno tiene sus propios usos. Sin embargo, solo 3 de ellos se pueden usar para documentar valores de retorno.

Para objetos con un conjunto conocido de propiedades (Variante A)

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

Esta sintaxis es ideal para objetos que se usan solo como parámetros para esta función y no requieren una descripción más detallada de cada propiedad. Se puede utilizar para @returnsasí .

Para objetos con un conjunto conocido de propiedades (Variante B)

Muy útiles son los parámetros con sintaxis de propiedades :

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

Esta sintaxis es ideal para objetos que se usan solo como parámetros para esta función y que requieren una descripción más detallada de cada propiedad. Esto no se puede usar para @returns.

Para objetos que se usarán en más de un punto en la fuente

En este caso, un @typedef es muy útil. Se puede definir el tipo en un momento de su fuente y utilizarlo como un tipo de @paramu @returnsu otras etiquetas jsdoc que pueden hacer uso de un tipo.

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

Luego puede usar esto en una @parametiqueta:

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

O en un @returns:

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

Para objetos cuyos valores son todos del mismo tipo

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

El primer tipo (cadena) documenta el tipo de las claves que en JavaScript siempre es una cadena o al menos siempre se coaccionará a una cadena. El segundo tipo (número) es el tipo del valor; Esto puede ser de cualquier tipo. Esta sintaxis también se puede utilizar @returns.

Recursos

Puede encontrar información útil sobre los tipos de documentación aquí:

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

PD:

para documentar un valor opcional que puede usar []:

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

o:

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

¿La variante 1 funciona con múltiples tipos de una propiedad? Al igual que {{dir: A|B|C }}?
CMCDragonkai

Cualquier tipo de anotación debería ser posible aquí, así que sí
Simon Zyx

¿Y para los objetos cuyas claves se generan dinámicamente? Me gusta{[myVariable]: string}
Frondor

135

Veo que ya hay una respuesta sobre la etiqueta @return, pero quiero dar más detalles al respecto.

En primer lugar, la documentación oficial de JSDoc 3 no nos da ningún ejemplo sobre @return para un objeto personalizado. Consulte https://jsdoc.app/tags-returns.html . Ahora, veamos qué podemos hacer hasta que aparezca algún estándar.

  • La función devuelve el objeto donde las claves se generan dinámicamente. Ejemplo: {1: 'Pete', 2: 'Mary', 3: 'John'}. Por lo general, iteramos sobre este objeto con la ayuda de for(var key in obj){...}.

    Posible JSDoc de acuerdo con 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 función devuelve el objeto donde las claves son constantes conocidas. Ejemplo: {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}. Podemos acceder fácilmente a las propiedades de este objeto: object.id.

    Posible JSDoc de acuerdo a https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4

    • Fíngelo.

      /**
       * 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
          }
      }
    • El monto completo.

      /**
       @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);
      }
    • Definir un tipo.

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

    De acuerdo con https://google.github.io/styleguide/javascriptguide.xml#JsTypes

    • El tipo de registro.

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

¿Alguien conoce una forma de generar esto en IntelliJ / Webstorm? Específicamente, estoy hablando de la tercera opción: definir un tipo.
Erez Cohen

Por favor elabora. ¿Desea tener alguna tecla de acceso directo o acceso directo en IDE para generar esos documentos o desea que su IDE entienda esos documentos? ¿Tal vez ambos?
vogdb

@vogdb ¿podría, por favor, echar un vistazo a este problema? Creo que este caso de uso no está cubierto con sus excelentes ejemplos: stackoverflow.com/questions/53191739/…
Pavel Polyakov

@PavelPolyakov He buscado. Realmente no sé cómo responder a tu pregunta. Estoy fuera de JS por un tiempo. Siéntase libre de editar mi respuesta si tiene alguna información nueva.
vogdb


2

Si se espera que un parámetro tenga una propiedad específica, puede documentar esa propiedad proporcionando una etiqueta @param adicional. Por ejemplo, si se espera que un parámetro de empleado tenga propiedades de nombre y departamento, puede documentarlo de la siguiente manera:

/**
 * 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 parámetro se desestructura sin un nombre explícito, puede darle al objeto uno apropiado y documentar sus propiedades.

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

Fuente: JSDoc


0

Hay una nueva @configetiqueta para estos casos. Se vinculan a lo anterior @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
¿Puede señalar la documentación de la @configetiqueta? No encontré nada en usejsdoc.org , y esta página sugiere que @configha quedado en desuso.
Dan Dascalescu

44
Creo que @configestá en desuso en este momento. YUIDoc recomienda usar en su @attributelugar.
Mike DeSimone
Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.