Add comments as per JSDOC3

Author: kunalkapadia

index.js

@@ -14,7 +14,7 @@ mongoose.connection.on('error', () => {
 
 const debug = require('debug')('express-mongoose-es6-rest-api:index');
 
-// listen on port port
+// listen on port config.port
 app.listen(config.port, () => {
 	debug(`started server on port ${config.port} (${config.env})`);
 });

server/controllers/user.js

@@ -1,16 +1,29 @@
 import User from '../models/user';
 
+/**
+ * Load user and append to req.
+ */
 export function load(req, res, next, id) {
 	User.get(id).then((user) => {
 		req.user = user;		// eslint-disable-line no-param-reassign
 		return next();
 	}).error((e) => next(e));
 }
 
+/**
+ * Get user
+ * @returns {User}
+ */
 export function get(req, res) {
 	return res.json(req.user);
 }
 
+/**
+ * Create new user
+ * @property {string} req.body.username - The username of user.
+ * @property {string} req.body.mobileNumber - The mobileNumber of user.
+ * @returns {User}
+ */
 export function create(req, res, next) {
 	const user = new User({
 		username: req.body.username,
@@ -22,6 +35,12 @@ export function create(req, res, next) {
 		.error((e) => next(e));
 }
 
+/**
+ * Update existing user
+ * @property {string} req.body.username - The username of user.
+ * @property {string} req.body.mobileNumber - The mobileNumber of user.
+ * @returns {User}
+ */
 export function update(req, res, next) {
 	const user = req.user;
 	user.username = req.body.username;
@@ -32,12 +51,22 @@ export function update(req, res, next) {
 		.error((e) => next(e));
 }
 
+/**
+ * Get user list.
+ * @property {number} req.query.skip - Number of users to be skipped.
+ * @property {number} req.query.limit - Limit number of users to be returned.
+ * @returns {User[]}
+ */
 export function list(req, res, next) {
 	const { limit = 50, skip = 0 } = req.query;
 	User.list({ limit, skip }).then((users) =>	res.json(users))
 		.error((e) => next(e));
 }
 
+/**
+ * Delete user.
+ * @returns {User}
+ */
 export function remove(req, res, next) {
 	const user = req.user;
 	user.removeAsync()

server/helpers/APIError.js

@@ -1,18 +1,31 @@
 import httpStatus from 'http-status';
 
+/**
+ * @extends Error
+ */
 class ExtendableError extends Error {
 	constructor(message, status, isPublic) {
 		super(message);
 		this.name = this.constructor.name;
 		this.message = message;
 		this.status = status;
 		this.isPublic = isPublic;
-		this.isOperational = true;
+		this.isOperational = true;	// This is required since bluebird 4 doesn't append it anymore.
 		Error.captureStackTrace(this, this.constructor.name);
 	}
 }
 
+/**
+ * Class representing an API error.
+ * @extends ExtendableError
+ */
 class APIError extends ExtendableError {
+	/**
+	 * Creates an API error.
+	 * @param {string} message - Error message.
+	 * @param {number} status - HTTP status code of error.
+	 * @param {boolean} isPublic - Whether the message should be visible to user or not.
+	 */
 	constructor(message, status = httpStatus.INTERNAL_SERVER_ERROR, isPublic = false) {
 		super(message, status, isPublic);
 	}

server/models/user.js

@@ -3,6 +3,9 @@ import mongoose from 'mongoose';
 import httpStatus from 'http-status';
 import APIError from '../helpers/APIError';
 
+/**
+ * User Schema
+ */
 const UserSchema = new mongoose.Schema({
 	username: {
 		type: String,
@@ -19,7 +22,28 @@ const UserSchema = new mongoose.Schema({
 	}
 });
 
+/**
+ * Add your
+ * - pre-save hooks
+ * - validations
+ * - virtuals
+ */
+
+/**
+ * Methods
+ */
+UserSchema.method({
+});
+
+/**
+ * Statics
+ */
 UserSchema.statics = {
+	/**
+	 * Get user
+	 * @param {ObjectId} id - The objectId of user.
+	 * @returns {Promise<User, APIError>}
+	 */
 	get(id) {
 		return this.findById(id)
 			.execAsync().then((user) => {
@@ -31,6 +55,12 @@ UserSchema.statics = {
 			});
 	},
 
+	/**
+	 * List users in descending order of 'createdAt' timestamp.
+	 * @param {number} skip - Number of users to be skipped.
+	 * @param {number} limit - Limit number of users to be returned.
+	 * @returns {Promise<User[]>}
+	 */
 	list({ skip = 0, limit = 50 } = {}) {
 		return this.find()
 			.sort({ createdAt: -1 })
@@ -40,4 +70,7 @@ UserSchema.statics = {
 	}
 };
 
+/**
+ * @typedef User
+ */
 export default mongoose.model('User', UserSchema);

server/routes/index.js

@@ -3,12 +3,12 @@ import userRoutes from './user';
 
 const router = express.Router();	// eslint-disable-line new-cap
 
-/* GET home page. */
+/** GET /health-check - Check service health */
 router.get('/health-check', (req, res) =>
 	res.send('OK')
 );
 
-// mount all routes here
+// mount user routes at /users
 router.use('/users', userRoutes);
 
 export default router;

server/routes/user.js

@@ -4,14 +4,23 @@ import * as userCtrl from '../controllers/user';
 const router = express.Router();	// eslint-disable-line new-cap
 
 router.route('/')
+	/** GET /api/users - Get list of users */
 	.get(userCtrl.list)
+
+	/** POST /api/users - Create new user */
 	.post(userCtrl.create);
 
 router.route('/:userId')
+	/** GET /api/users/:userId - Get user */
 	.get(userCtrl.get)
+
+	/** PUT /api/users/:userId - Update user */
 	.put(userCtrl.update)
+
+	/** DELETE /api/users/:userId - Delete user */
 	.delete(userCtrl.remove);
 
+/** Load user when API with userId route parameter is hit */
 router.param('userId', userCtrl.load);
 
 export default router;

server/tests/misc-tests.js

@@ -41,5 +41,5 @@ describe('## Misc', () => {
 					done();
 				});
 		});
-	})
+	});
 });