Come documentare il reso in JavaScript

Question

Sto scrivendo la mia libreria per il progetto al lavoro per un'applicazione browser e sto avendo lo stesso vecchio problema a decidere come commentare il codice.

Sto cercando di seguire la sintassi JsDoc, ma probabilmente continuerò il modo Google Closure Compiler. Potrei finire con l'utilizzo di due tag @return e @returns nella documentazione, solo per motivi di portabilità (quando imposto l'auto-generazione della documentazione).

Ora, la domanda, come si documenta il ritorno di un oggetto anonimo personalizzato da una funzione? Per esempio:

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

JsDoc ha un esempio di come un @param può essere documentato aspettarsi oggetto con alcuni campi, ma non il tag @returns. Allo stesso modo, la documentazione di Google Closure Compiler di un tipo di record è vaga e non ha alcun esempio per risolverlo.

Answer 1

Se mettere questo in cima alla funzione di

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

la chiusura-compilatore utilizza un sottoinsieme del JSDoc annotations (e aggiunge alcune propria). Vedi lo annotation reference for the compiler per il set completo. Un'annotazione JSDoc è simile a un'annotazione JavaDoc ed è un blocco di commenti che inizia con /** (due stelle). Mentre ogni riga del commento inizia spesso con il proprio *, questa è una convenzione che non è richiesta. È consentito un solo tag JSDoc per riga, ma gli argomenti per un tag possono estendersi su più righe.

L'annotazione si applica in genere alla seguente dichiarazione. Ecco alcuni esempi:

variabile

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

cast di tipo

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

nota la parentesi in più

Nominato Funzione

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

Funzione espressioni

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

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

Typedef

tipi complessi (tra cui sindacati, e tipi di record) possono essere alias per convenienza e la manutenibilità utilizzando un typedef. Queste annotazioni possono essere lunghe, ma possono essere suddivise su più righe per essere leggibili.

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

Per l'esempio originale, esistono diversi modi per annotare un valore di ritorno di tale funzione. Uno dei più specifico e comunque conveniente è il tipo di record:

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

nota l'extra {}. Inoltre, tieni presente che i tipi di record non impediranno la ridenominazione delle proprietà.

Questa annotazione indica al compilatore che la funzione restituisce un tipo anonimo con le proprietà username, password e enabled. Altre opzioni valide sarebbero definire un'interfaccia altrove e tipografare il valore restituito come tale interfaccia. L'annotazione meno specifica sarebbe Object o *.

Per visualizzare una vasta gamma di possibili annotazioni, dare un'occhiata allo extern files in the Compiler project.

Answer 3

Uno dei modi più semplici e portabili per farlo è il seguente, utilizzando return come parola chiave. 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 
     }; 
} 

Se si dispone di usarlo in più posti, si dovrà duplicarlo, o utilizzare @typedef, ma non ho capito come aggiungere commenti a @typedef così io uso qualcosa come il seguente

/** 
* @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 
     }; 
} 

potete anche provare il suggerimento qui How can I document a type in webstorm using just jsdoc?