Cómo documentar la devolución en JavaScript

Question

Estoy escribiendo mi propia biblioteca para el proyecto en el trabajo para una aplicación de navegador y estoy teniendo el mismo viejo problema para decidir cómo comentar el código.

Intento seguir la sintaxis JsDoc, pero probablemente continúe la forma Google Closure Compiler. Puedo terminar utilizando dos etiquetas @return y @returns en la documentación, solo por portabilidad (cuando configuro la auto-generación de la documentación).

Ahora, la pregunta, ¿cómo documenta la devolución de un objeto anónimo personalizado desde una función? Por ejemplo:

return { 
    username: 'username', 
    password: 'password', 
    enabled: true 
}; 

jsdoc tiene un ejemplo de cómo un @param puede documentarse a esperar objeto con ciertos campos, pero no la etiqueta @returns. Del mismo modo, la documentación del Compilador de cierres de Google de un Tipo de registro es vaga y no tiene ningún ejemplo para resolverlo.

Answer 1

Si poner esto en la parte superior de la función

function myFunction() { 
    /** 
    * Description of my function 
    * @return {!Object.<string, string|boolean>} Returns an object containing username, password and enabled information 
    */ 

    // Do stuff 
    return { 
     username: 'username', 
     password: 'password', 
     enabled: true 
    } 
} 

Answer 2

El Cierre compilador utiliza un subconjunto de la JSDoc annotations (y añade unos pocos de su propia). Vea el annotation reference for the compiler para el conjunto completo. Una anotación JSDoc es similar a una anotación JavaDoc y es un bloque de comentarios que comienza con /** (dos estrellas). Si bien cada línea del comentario a menudo comienza con su propio *, esa es una convención que no se requiere. Solo se permite una etiqueta JSDoc por línea, pero los argumentos para una etiqueta pueden abarcar varias líneas.

La anotación generalmente se aplica a la siguiente declaración. He aquí algunos ejemplos:

variable

/** @type {string} */ var a; 

conversión de tipo

var b = /** @type {string} */ (window['foo']); 

nota del paréntesis adicional

función llamada

/** 
* @param {string} bar 
* @return {boolean} 
*/ 
function foo(bar) { return true; } 

expresiones de función

/** @type {function(string):boolean} */ 
var foo = function(bar) { return true; } 

var foo2 = 
    /** 
    * @param {string} bar 
    * @return {boolean} 
    */ 
    function(bar) { return true; } 

typedef

tipos complejos (incluidos los sindicatos, y los tipos de registro) se pueden crear alias para mayor comodidad y facilidad de mantenimiento usando un typedef. Estas anotaciones pueden ser largas, pero se pueden dividir en varias líneas para facilitar su lectura.

/** @typedef {{ 
*    foo:string, 
*    bar:number, 
*    foobar:number|string 
*   }} 
*/ 
var mytype; 

Para su ejemplo original, hay varias formas posibles de anotar dicho valor de retorno de la función. Uno de los más específicos y todavía conveniente es el tipo de registro:

/** @return {{username:string, password:string, enabled:boolean}} */ 
function() { 
    return { 
    username: 'username', 
    password: 'password', 
    enabled: true 
    } 
} 

Nota extra {}. También tenga en cuenta que los tipos de registros no evitarán el cambio de nombre de propiedad.

Esta anotación le dice al compilador que la función devuelve un tipo anónimo con las propiedades username, password y enabled. Otras opciones válidas serían definir una interfaz en otro lugar y encasillar el valor de retorno para que sea esa interfaz. La anotación menos específica sería Object o *.

Para ver una amplia gama de anotaciones posibles, eche un vistazo a extern files in the Compiler project.

Answer 3

Una de las formas agradables y portátiles de hacerlo es como la siguiente, utilizando return como palabra clave. https://github.com/senchalabs/jsduck/wiki/%40return

/** 
* @return {object} return An object with the following properties 
* @return {string} return.username Some username 
* @return {string} return.password Some password 
* @return {boolean} return.enabled Is the user enabled? 
*/ 
function getObj() { 
    return { 
     username: 'username', 
     password: 'password', 
     enabled: true 
     }; 
} 

Si usted tiene que utilizar en múltiples lugares, se tendría que duplicar o utilice @typedef, pero no he encontrado la manera de añadir comentarios a @typedef lo que utilizar algo como lo siguiente

/** 
* @typedef {username:string, password:string, enabled:boolean} MyType 
* 
* username: The name of the user 
* password: Some password 
* enabled: Is the user enabled? 
*/ 

/** 
* @return {MyType} 
*/ 
function getObj() { 
    return { 
     username: 'username', 
     password: 'password', 
     enabled: true 
     }; 
} 

también puede probar la sugerencia aquí How can I document a type in webstorm using just jsdoc?