commentando le funzioni di callback

Question

Solo curioso quale sia un buon modo per commentare quali parametri saranno passati alla funzione di callback.

Supponiamo di avere il seguente codice e incompleti commenti

/** 
* an utterly useless function 
* 
* @param {String} an useless string 
* @param {Boolean} an useless boolean 
* @param {Function} ??? 
*/ 

function Useless (str, bool, callback) { 
    callback(str, bool); 
} 

Che cosa è un buon modo per dire callback verrà chiamata con str e bool sono i parametri?

Answer 1

Di solito si sarà solo scrivere un invocazione della funzione con i nomi di lingua:

/* 
* @param {String} input: the text 
* @param {Function} callback(output, hasChanged): called after calculation 
*/ 

Oppure, se i parametri devono spiegazione, è possibile utilizzare una descrizione più righe:

/* 
* @param {String} input: the text 
* @param {Function} callback(result, change) 
      the function that is called after calculation 
      result {String}: the output of the computation 
      change {Bool}: whether a change has occured 
*/ 

Answer 2

Non conosco nessuna convenzione per questo. Vorrei solo usare:

@param {Function} Called on success with the response (string) as the first param and the status code (int) as the second 

Sono consapevole che è piuttosto prolisso.

Un'altra opzione sarebbe farlo in questo modo (simile a come jQuery lo fa, non in codice che sono consapevole, ma nella loro documentazione)

@param {Function} onSuccess(response, statusCode) 

Ecco un esempio http://api.jquery.com/jQuery.ajax/ E 'diverso, naturalmente, poiché questo è un oggetto opzioni e la documentazione ha una struttura diversa dalla documentazione inline. Ma guarda i callback e vedrai la somiglianza.

È inoltre consigliabile utilizzare callback (response, statusCode) piuttosto che callback (string, int) per maggiore chiarezza. Se devi sceglierne uno. Significato prima del tipo.

Answer 3

Beh, ci ci sono molti modi per aggiungere commenti in javascript; Ecco la mia raccomandazione/best practice .

utilizzando // è meglio di /* */ perché è possibile utilizzare quest'ultimo per estrarre un intero blocco contenente altri commenti. Tuttavia, se si desidera utilizzare uno strumento di generazione automatica della documentazione, è necessario utilizzare commenti simili allo stile javaDoc.

Questo è un esempio che avrebbe funzionato con YUI DOC (migliore) http://developer.yahoo.com/yui/yuidoc/#start

/** 
* This is a description 
* @namespace My.Namespace 
* @method myMethodName 
* @param {String} str - some string 
* @param {Object} obj - some object 
* @param {requestCallback} callback - The callback that handles the response. 
* @return {bool} some bool 
*/ 
    function SampleFunction (str, obj, callback) { 
     var isTrue = callback(str, obj); // do some process and returns true/false. 
     return isTrue ; 
    } 

Altre params Esempi: - http://usejsdoc.org/tags-param.html

Sperando che questo vi aiuterà :) funzione