title: What's the proper way to document callbacks with jsdoc?
body: <p>I've spent quite a while scouring the internet looking for the best way to properly document callbacks with jsdoc, but unfortunately, I haven't found a great one yet.</p>
  
  <p>Here's my question:</p>
  
  <p>I'm writing a Node.js library for developers. This library provides multiple classes, functions, and methods that developers will be working with.</p>
  
  <p>In order to make my code clear and understandable, as well as to (hopefully) auto-generate some API documentation in the future, I've started using <a href="http://usejsdoc.org/" rel="noreferrer">jsdoc</a> in my code to self-document what's happening.</p>
  
  <p>Let's say I define a function like the following:</p>
  
  <pre><code>function addStuff(x, y, callback) {
    callback(x+y);
  });
  </code></pre>
  
  <p>Using jsdoc, I'm currently documenting this function as follows:</p>
  
  <pre><code>/**
    * 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);
  });
  </code></pre>
  
  <p>I feel like the above solution is kinda hack-ish, since there's no way for me to specify in absolute terms what the callback function should accept.</p>
  
  <p>Ideally, I'd like to do something like:</p>
  
  <pre><code>/**
    * 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);
  });
  </code></pre>
  
  <p>The above seems like it'd allow me to more simply convey what my callback needs to accept.  Does that make sense?</p>
  
  <p>I guess my question is simple: what's the best way to clearly document my callback functions with jsdoc?</p>
  
  <p>Thank you for your time.</p>