90

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

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

4

5 に答える 5

119

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);
}
于 2014-06-14T01:14:01.073 に答える
53

もう 1 つの可能性は、コールバックに渡される値を次のように記述することです。

/**
  * 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}。

于 2016-07-26T09:45:03.110 に答える
9

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

ここに画像の説明を入力 ここに画像の説明を入力

于 2018-04-17T03:15:16.720 に答える
4 
@param {function(number):void} myCallback

2021 年現在、VS Code と WebStorm でうまく動作します

于 2021-03-26T01:55:26.127 に答える