javascript - example - jsdoc forma correcta de documentar socket.on(''evento'', función(){}) y enrutador de rutas

jsdoc return

Question

Cómo documentar API usando jsdoc que tiene la siguiente forma (archivo único)

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

Mi única idea es agregar @namespace sobre las exportaciones y @lends sobre las funciones anónimas, pero eso da como resultado una documentación vacía.

Answer 1

Estoy usando Angular y luego el documento Angular para JSDoc. Como tal, estoy documentando mi clase principal y funciones similares a las siguientes.

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

Entonces, con tu texto de arriba, podría verse como:

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