19

How to document API using jsdoc which has following form (single file)

// api.js

exports.addSocketEvents = function(socket) {
   /**
    * This will do that and ...
    * @param {Object} data Some data
    * @param {string} data.bla Something about bla
    * @param {number} data.n Some number
    */
   socket.on('something_1', function(data) { ... });

   /**
    * Another function that will do ..
    * @param {string} id of something
    */
   socket.on('something_2', function(id) { ... });

   ...
};

exports.addRoutes = function(app) {
    /**
     * PATCH /something/:id/juhu
     * Will do this and that and will respond with ...
     * @param {string} _id Id of bonus document
     */
    app.patch('/something/:id/juhu', function(req, res) {...});

    /**
     * GET /something
     * Will fetch and respond back with ...
     */
    app.get('/something', function(req, res) {...});
    ...
};

My only idea is to add @namespace above exports and @lends above anonymous functions but that results in empty documentation.

Srle
  • 9,554
  • 7
  • 30
  • 58

1 Answers1

1

I am using Angular and then the Angular doc for JSDoc. As such, I am documenting my parent class and functions similar to the following.

/**
 * @class MyApp.Teams
 * @ngdoc class
 * @memberOf MyApp
 * @description
 * Module to handle the interface to the Teams, data and views.
 */

angular.module('MyApp').factory( ...

/**
 * @name TeamRecord
 * @ngdoc factory
 * @memberOf MyApp.Teams
 * @returns Record Clears the Structure to  ""
 * @description
 * Team Data Record structure
 */

So, with your text above, it might look like:

/**
 * @class MyApp.socketio
 * @ngdoc class
 * @memberOf MyApp
 * @description
 * Module to handle the interface to the Teams, data and views.
 */

/**
 * @name addSocketEvens
 * @ngdoc function
 * @memberOf MyApp.socketio
 * @param {Object} data Some data
 * @param {string} data.bla Something about bla
 * @param {number} data.n Some number
 * @description
 * This will do that and ...
 */
exports.addSocketEvents = function(socket) {
   socket.on('something_1', function(data) { ... });

   /**
    * Another function that will do ..
    * @param {string} id of something
    */
   socket.on('something_2', function(id) { ... });

   ...
};

/**
 * @name addRoutes
 * @ngdoc function
 * @memberOf MyApp.socketio
 * @param {string} _id Id of bonus document
 * @description
 * Will do this and that and will respond with ...
 */
exports.addRoutes = function(app) {
    app.patch('/something/:id/juhu', function(req, res) {...});

    /**
     * GET /something
     * Will fetch and respond back with ...
     */
    app.get('/something', function(req, res) {...});
    ...
};
Steven Scott
  • 6,905
  • 5
  • 48
  • 88
  • Running jsdoc command against this file all anonymous functions remain ignored(undocumented). Besides, i would try to avoid using @class if i can, in this case documentation will contain new socketio() which can be misleading clue to someone who will read the docs. – Srle Oct 23 '15 at 17:06
  • You can remove the @class as I can see why you would not want them. Are you running the latest JSDoc? I did find this question as well. https://stackoverflow.com/questions/8071897/how-to-document-anonymous-functions-closure-with-jsdoc-toolkit – Steven Scott Oct 23 '15 at 22:07