javascript - objects - Colección de documentos(matriz de tipo) devuelve valor y parámetro en JSDoc

jsdoc return

Question

Cómo documentar el valor de retorno de la Array (y los parámetros) en JSDoc cuando los elementos de la matriz pueden ser cualquiera de los siguientes:

• Un tipo (por ejemplo, String , Array ).
• Un objeto literal.

Answer 1

Aunque puede encontrar que la orientación que se ofrece en algunas de las otras respuestas funciona para usted, prefiero esta sintaxis:

/**
 * @return {Array<String>} ...
 */

Y en comparación con la orientación que otros han ofrecido, creo que esto se acerca más a sus expectativas en función del ejemplo que da en su pregunta.

Aquí hay una gran fuente de información sobre JSDoc: https://wiki.servoy.com/display/public/DOCS/JSDoc+Annotations

Answer 2

Dado un parámetro de screenings :

screenings = [
    {
        timestamp: 1440157537,
        url: ''https://.com/a/22787287/1269037'',
    },
    {
        timestamp: ...,
        url: ...,
    },
];

Puedes documentarlo de una de las tres formas:

Utilizando @typedef :

/**
 * @typedef {Object} screening
 * @property {Number} timestamp - UNIX timestamp.
 * @property {String} url - Booking URL.
 */

/**
 * @param {screening[]}
 */
function positionTimes (screenings) {}

Cuando hay varias funciones que utilizan una variación del objeto de screening , puede usar un espacio de nombres de funciones, por ejemplo,

/**
 * @typedef {Object} positionTimes~screening
 * @property {Number} timestamp - UNIX timestamp.
 * @property {String} url - Booking URL.
 */

/**
 * @param {positionTimes~screening[]}
 */
function positionTimes (screenings) {}

/**
 * @typedef {Object} filterTimes~screening
 * @property {Number} timestamp - UNIX timestamp.
 * @property {String} url - Booking URL.
 */

/**
 * @param {filterTimes~screening[]}
 */
function filterTimes (screenings) {}

Documentando las propiedades de los valores en una matriz :

/**
 * @param {Object[]} screenings
 * @param {Number} screenings[].timestamp - Unix timestamp.
 * @param {String} screenings[].url - Booking URL.
 */
function positionTimes (screenings) {}

Esto no funcionará para describir los tipos de @return ed porque el valor de retorno no toma un nombre.

Usando una definición de colección:

/**
 * @param {Array.<{timestamp: Number, url: String}>} screenings
 */
function positionTimes (screenings) {}

Una ventaja de este enfoque es que es de una sola línea, por lo que puede usarlo en declaraciones de @return , donde el segundo método no funcionará.

La desventaja del enfoque de definición de colección es que no permite describir valores de propiedades.

Answer 3

En la documentación para JSDoc en http://usejsdoc.org/ hay un ejemplo dado para una matriz con miembros de tipo MyClass . Hay dos posibilidades. Una se ve así:

@param{MyClass[]}

El otro como este:

@param{Array.<MyClass>}

Sé consciente de la . entre Array y < .

Answer 4

Según doco @returns

/** 
 * @returns {Array} Lines from the file.
 */
function readLines(filepath) {
}

También vea .

Answer 5

Si está buscando cómo documentar el tipo de objetos en una matriz, quiere algo como esto:

 /**
  * @param {String[]} aliases
  */

http://code.google.com/p/jsdoc-toolkit/wiki/TagParam#Parameter_Type_Information