Каков правильный способ документирования обратных вызовов с помощью jsdoc?

Я потратил немало времени, пытаясь найти интернет, ищущий лучший способ правильно документировать обратные вызовы с помощью jsdoc, но, к сожалению, я еще не нашел отличный.

Вот мой вопрос:

Я пишу библиотеку Node.js для разработчиков. Эта библиотека предоставляет несколько классов, функций и методов, с которыми будут работать разработчики.

Чтобы сделать мой код понятным и понятным, а также (надеюсь) автоматически создать некоторую документацию API в будущем, я начал использовать jsdoc в моем коде для самообучения, что происходит.

Скажем, я определяю функцию, подобную следующей:

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

Используя jsdoc, я в настоящее время документирую эту функцию следующим образом:

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

Мне кажется, что вышеупомянутое решение является своеобразным hack-ish, так как нет никакого способа указать в абсолютном выражении то, что должна принять функция обратного вызова.

В идеале я хотел бы сделать что-то вроде:

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

Вышеприведенное кажется, что это позволило бы мне более просто передать то, что мой callback должен принять. Это имеет смысл?

Я думаю, мой вопрос прост: какой лучший способ четко документировать мои функции обратного вызова с помощью jsdoc?

Спасибо за ваше время.

Ответ 1

JSDoc 3 имеет тег @callback именно для этой цели. Вот пример использования:

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

Ответ 2

Другая возможность - описать значение, переданное обратному вызову следующим образом:

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

Чтобы записать возвращаемый тип обратного вызова, используйте @param {function(int):string}.

Ответ 3

Обходной путь, чтобы VSCode понимал это

/**
 * @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) {
    // ...
}