[解決済み] 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);
});

コールバック関数が受け取るべきものを絶対的に指定する方法がないので、上記の解決策はちょっとハック的な気がします。

理想的には、次のようなことをしたいです。

/**
  * 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で私のコールバック関数を明確に文書化する最良の方法は何でしょうか？

お時間をいただき、ありがとうございます。

どのように解決するのですか？

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