如何使用具有以下格式(单个文件)的jsdoc来记录API
// 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
,但这会导致文档空白。
答案 0 :(得分:1)
我正在使用Angular,然后使用Angular doc for 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) {...});
...
};