comentando funciones de devolución de llamada

Question

Es curioso saber cuál es una buena forma de comentar qué parámetros se pasarán a la función de devolución de llamada.

Supongamos que tenemos el siguiente código y incompletas comentarios

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

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

Qué es una buena manera de decir devolución de llamada se llama str y con bool son parámetros?

Answer 1

lo general, usted acaba de escribir una invocación de la función con nombres de habla:

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

O, si los parámetros necesitan explicación, puede utilizar una descripción de varias líneas:

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

No conozco ninguna convención para esto. Yo solo usaría:

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

Soy consciente de que es bastante detallado.

Otra opción sería hacerlo así (similar a cómo jQuery lo hace, no en código que yo sepa, pero en su documentación)

@param {Function} onSuccess(response, statusCode) 

He aquí un ejemplo http://api.jquery.com/jQuery.ajax/ Es diferente, por supuesto, ya que este es un objeto de opciones y la documentación tiene una estructura diferente a la documentación en línea. Pero mira las devoluciones de llamada y verás la similitud.

También es una idea mucho mejor utilizar la devolución de llamada (respuesta, código de estado) que la devolución de llamada (cadena, int) para mayor claridad. Si tiene que elegir uno que sea. Significado antes del tipo.

Answer 3

Bueno, hay hay muchas formas de agregar comentarios en javascript; Aquí está mi recomendación /mejores prácticas.

usando // es mejor que /* */ porque luego puede utilizar este último para eliminar un bloque completo que contiene otros comentarios. Sin embargo, si desea utilizar una herramienta de generación automática de documentación, debe usar comentarios similares al estilo javaDoc.

Este es un ejemplo que trabajaría con DOC YUI (mejor) 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 ; 
    } 

Otros params Ejemplos: - http://usejsdoc.org/tags-param.html

Con la esperanza de que esto le ayudará :) función