javascript - objects - Colección de documentos(matriz de tipo) devuelve valor y parámetro en JSDoc
jsdoc return (5)
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
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.
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.
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 < .
Según doco @returns
/**
* @returns {Array} Lines from the file.
*/
function readLines(filepath) {
}
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