javascript - documentar - jsdoc example

¿Cuál es la forma correcta de documentar devoluciones de llamada con jsdoc?

Question

He pasado un buen rato buscando en Internet la mejor manera de documentar apropiadamente las devoluciones de llamada con jsdoc, pero desafortunadamente, todavía no he encontrado una buena.

Aquí está mi pregunta:

Estoy escribiendo una biblioteca Node.js para desarrolladores. Esta biblioteca proporciona múltiples clases, funciones y métodos con los que los desarrolladores trabajarán.

Para hacer que mi código sea claro y comprensible, y para (con suerte) autogenerar cierta documentación API en el futuro, comencé a usar jsdoc en mi código para auto-documentar lo que está sucediendo.

Digamos que defino una función como la siguiente:

function addStuff(x, y, callback) {
  callback(x+y);
});

Usando jsdoc, actualmente estoy documentando esta función de la siguiente manera:

/**
  * Add two numbers together, then pass the results to a callback function.
  *
  * @function addStuff
  * @param {int} x - An integer.
  * @param {int} y - An integer.
  * @param {function} callback - A callback to run whose signature is (sum), where
  *  sum is an integer.
  */
function addStuff(x, y, callback) {
  callback(x+y);
});

Siento que la solución anterior es un poco hack-ish, ya que no hay forma de que especifique en términos absolutos qué debería aceptar la función de devolución de llamada.

Idealmente, me gustaría hacer algo como:

/**
  * Add two numbers together, then pass the results to a callback function.
  *
  * @function addStuff
  * @param {int} x - An integer.
  * @param {int} y - An integer.
  * @param {callback} callback - A callback to run.
  * @param {int} callback.sum - An integer.
  */
function addStuff(x, y, callback) {
  callback(x+y);
});

Lo anterior parece que me permitiría transmitir más simplemente lo que mi devolución de llamada debe aceptar. ¿Tiene sentido?

Supongo que mi pregunta es simple: ¿cuál es la mejor manera de documentar claramente mis funciones de devolución de llamada con jsdoc?

Gracias por tu tiempo.

Answer 1

JSDoc 3 tiene una etiqueta @callback para exactamente este propósito. Aquí hay un ejemplo de uso:

/**
 * Callback for adding two numbers.
 *
 * @callback addStuffCallback
 * @param {int} sum - An integer.
 */

/**
 * Add two numbers together, then pass the results to a callback function.
 *
 * @param {int} x - An integer.
 * @param {int} y - An integer.
 * @param {addStuffCallback} callback - A callback to run.
 */
function addStuff(x, y, callback) {
  callback(x+y);
}

Answer 2

Otra posibilidad es describir el valor pasado a la devolución de llamada de esta manera:

/**
  * Add two numbers together, then pass the results to a callback          function.
  *
  * @function addStuff
  * @param {int} x - An integer.
  * @param {int} y - An integer.
  * @param {function(int)} callback - A callback to run whose signature is (sum), where
  *  sum is an integer.
  */
function addStuff(x, y, callback) {
    callback(x+y);
});

Para documentar el tipo de devolución de la devolución de llamada, use @param {function(int):string} .

Answer 3

Una solución para hacer que VSCode lo entienda

/**
 * @typedef {function(FpsInfo)} fpsCallback
 * @callback fpsCallback
 * @param {FpsInfo} fps Fps info object
 */

 /**
 * @typedef {Object} FpsInfo
 * @property {number} fps The calculated frames per second
 * @property {number} jitter The absolute difference since the last calculated fps
 * @property {number} elapsed Milliseconds ellapsed since the last computation
 * @property {number} frames Number of frames since the last computation
 * @property {number} trigger Next computation will happen at this amount of frames
 */

/**
 * FPS Meter - Returns a function that is used to compute the framerate without the overhead of updating the DOM every frame.
 * @param {fpsCallback} callback Callback fired every time the FPS is computed
 * @param {number} [refreshRate=1] Refresh rate which the fps is computed and the callback is fired (0 to compute every frame, not recommended)
 * @returns {function} Returns a function that should be called on every the loop tick
 * @author Victor B - www.vitim.us - github.com/victornpb/fpsMeter
 */
function createFpsMeter(callback, refreshRate = 1) {
    // ...
}