example - ¿Cómo documentar las devoluciones de llamada utilizando JSDoc?

jsdoc npm

Question

Dada una función de Javascript que toma las funciones de devolución de llamada como parámetros:

var myFunction = function(onSuccess, onFailure) {...}

¿Cómo documento el tipo de devolución y los argumentos de onSuccess ?

Answer 1

En JSDoc 3.1 y @callback posteriores, puede usar la nueva etiqueta @callback para describir la función de devolución de llamada en un bloque de comentarios separado. Luego puede referirse a la devolución de llamada en los documentos para su método.

Aquí hay un ejemplo:

/** @class */
function MyClass() {}

/**
 * Do something.
 * @param {MyClass~onSuccess} cb - Called on success.
 */
MyClass.prototype.myFunction = function(cb) {
    // code
};

/**
 * Callback used by myFunction.
 * @callback MyClass~onSuccess
 * @param {number} resultCode
 * @param {string} resultMessage
 */

Vea Usar JSDoc para más información.

Answer 2

Parece que esta funcionalidad aún no existe.

Esta funcionalidad fue agregada a partir de JSDoc 3.1. Ver:

• http://code.google.com/p/jsdoc-toolkit/issues/detail?id=319
• https://github.com/jsdoc3/jsdoc/issues/260

para una discusión relacionada.