jsdoc로 콜백을 문서화하는 적절한 방법은 무엇입니까?

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

---

또 다른 가능성은 다음과 같이 콜백에 전달 된 값을 설명하는 것입니다.

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

---

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

ReferenceURL : https://stackoverflow.com/questions/24214962/whats-the-proper-way-to-document-callbacks-with-jsdoc