javascript - vscode - jsdoc variable

¿Cómo describir los argumentos de "objeto" en jsdoc?

Question

// 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 se debe estructurar el objeto de parámetros? Por ejemplo, debería ser algo como:

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

Answer 1

Desde la página wiki de @param :

Parámetros con propiedades

Si se espera que un parámetro tenga una propiedad en 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 a la correspondiente @param, pero parece haber quedado en desuso ( ejemplo aquí ).

Answer 2

Hay una nueva etiqueta @config para estos casos. Se enlazan a la 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
 */

Answer 3

Para usar la etiqueta @return {{field1: Number, field2: String}} , consulte: http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDoc

Answer 4

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 los 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 los objetos que se usan solo como parámetros para esta función y no requieren una descripción más detallada de cada propiedad. También se puede utilizar para @returns .

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

Muy útil es la sintaxis de parámetros con propiedades :

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

Esta sintaxis es ideal para los 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 puede ser usado 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. Puede definir el tipo en un punto de su fuente y usarlo como un tipo para @param o @returns u 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
 */

Puedes usar esto en una etiqueta @param :

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

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 será obligado a una cadena. El segundo tipo (número) es el tipo del valor; Esto puede ser de cualquier tipo. Esta sintaxis puede usarse también para @returns .

Recursos

Se puede encontrar información útil sobre tipos de documentación aquí:

http://usejsdoc.org/tags-type.html

PD:

para documentar un valor opcional puede usar []:

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

o:

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

Answer 5

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 la devolución de un objeto personalizado. Por favor, visite http://usejsdoc.org/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''} . Generalmente, iteramos sobre este objeto con la ayuda de for(var key in obj){...} .

  Posible JSDoc según 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 según 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 a 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 || {}
        }
    }