Я потратил довольно много времени на поиск в Интернете, чтобы найти лучший способ правильно документировать обратные вызовы с помощью 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);
});

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

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

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

Похоже, что вышеизложенное позволило бы мне более просто передать то, что должен принять мой обратный вызов. Имеет ли это смысл?

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

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