JSDoc właściwy sposób udokumentować socket.on ('zdarzenie', function() {}) i trasy obsługi

Question

Jak udokumentować za pomocą API JSDoc który następującą postać (pojedynczy plik)

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

Mój pomysł jest tylko dodać powyżej nadekranowanych @namespace i @lends nad anonimowymi funkcjami, ale powoduje to pustą dokumentację.

Answer 1

Używam Angular, a następnie Angular Doc dla JSDoc. W związku z tym dokumentuję swoją klasę nadrzędną i funkcje podobne do poniższych.

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

Tak, z tekstu powyżej, może wyglądać następująco:

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