JSDoc надлежащим образом документировать socket.on («событие», функция() {}) и маршруты обработчик

Question

Как документировать API с помощью JSDoc, который следующий вид (один файл)

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

Моя единственная идея заключается в том добавить @namespace выше экспорта и @lends над анонимными функциями, но это приводит к пустой документации.

Answer 1

Я использую Angular, а затем Angular doc для JSDoc. Таким образом, я документирую свой родительский класс и функции, подобные приведенным ниже.

/** 
* @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 
*/ 

Итак, с текстом выше, это может выглядеть следующим образом:

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