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