docs(api): controllers and services improve

Author: balthazar

api/controllers/language.controller.js

@@ -2,6 +2,11 @@
 
 import { LanguageService } from '../services';
 
+/**
+ * Get all languages
+ *
+ * GET /languages [None]
+ */
 exports.getAll = (req, res) => {
   LanguageService.getAll().then(languages => {
     res.status(200).send(languages);
@@ -10,6 +15,11 @@ exports.getAll = (req, res) => {
   });
 };
 
+/**
+ * Get a specific language by its id
+ *
+ * GET /languages/:id [None]
+ */
 exports.getOne = (req, res) => {
   LanguageService.getOne(req.params.id).then(language => {
     res.status(200).send(language);
@@ -18,6 +28,11 @@ exports.getOne = (req, res) => {
   });
 };
 
+/**
+ * Create a text
+ *
+ * POST /languages [Admin]
+ */
 exports.create = (req, res) => {
   LanguageService.create(req.body).then(language => {
     res.status(200).send(language);

api/controllers/text.controller.js

@@ -2,6 +2,11 @@
 
 import { TextService } from '../services';
 
+/**
+ * Get all texts
+ *
+ * GET /texts [None]
+ */
 exports.getAll = (req, res) => {
   TextService.getAll()
     .then(texts => {
@@ -12,6 +17,11 @@ exports.getAll = (req, res) => {
     });
 };
 
+/**
+ * Get a random text
+ *
+ * GET /texts/rand [None]
+ */
 exports.getRandom = (req, res) => {
   TextService.getRandom()
     .then(text => {
@@ -22,6 +32,11 @@ exports.getRandom = (req, res) => {
     });
 };
 
+/**
+ * Get a text by its id
+ *
+ * GET /texts/:id [None]
+ */
 exports.getOne = (req, res) => {
   TextService.getOne(req.params.id)
     .then(text => {
@@ -32,6 +47,11 @@ exports.getOne = (req, res) => {
     });
 };
 
+/**
+ * Create a text
+ *
+ * POST /texts [Admin]
+ */
 exports.create = (req, res) => {
   TextService.create(req.body.title, req.body.data, req.body.language, req.user.id)
     .then(text => {
@@ -42,6 +62,11 @@ exports.create = (req, res) => {
     });
 };
 
+/**
+ * Cast a vote on a text
+ *
+ * POST /text/:id/vote [User]
+ */
 exports.castVote = (req, res) => {
   TextService.castVote(req.params.id, req.user.id, req.body.value)
     .then(() => {

api/controllers/user.controller.js

@@ -6,9 +6,7 @@ import { UserService } from '../services';
 /**
  * Return the current user
  *
- * @param {Object} req Express request
- * @param {Object} res Exress result
- * @returns {Object} user
+ * GET /users/me [User]
  */
 exports.getMe = (req, res) => {
   res.status(200).send(req.user);
@@ -17,16 +15,16 @@ exports.getMe = (req, res) => {
 /**
  * Update the current user
  *
- * @param {Object} req Express request
- * @param {Object} res Exress result
- * @returns {Null} nothing
+ * PUT /users/me [User]
  */
 exports.putMe = (req, res) => {
   res.status(404).send({ message: 'Route under construction.' });
 };
 
 /**
- * Get all users, for admins only
+ * Get all users
+ *
+ * GET /users [Admin]
  */
 exports.getAll = (req, res) => {
   UserService.getAll()
@@ -40,6 +38,8 @@ exports.getAll = (req, res) => {
 
 /**
  * Create a new result for a user
+ *
+ * POST /users/me/game [User]
  */
 exports.newResult = (req, res) => {
   UserService.newResult(_.assign(req.body, { userId: req.user.id }))

api/services/user.service.js

@@ -7,18 +7,40 @@ import { propsDiffer } from './utils.service';
 import { User, Test } from '../models';
 import GithubService from './github.service';
 
+/**
+ * Get all users.
+ * @returns {Promise}
+ */
 exports.getAll = () => {
   return User.findAll();
 };
 
+/**
+ * Get a user by its id.
+ *
+ * @param id {Number}
+ * @returns {Promise}
+ */
 exports.getById = id => {
   return User.findById(id);
 };
 
+/**
+ * Get a user by its github identifier
+ *
+ * @param id {Number}
+ * @returns {Promise}
+ */
 exports.getByGithub = id => {
   return User.findOne({ where: { githubId: id } });
 };
 
+/**
+ * Get user average wpm across all his results.
+ *
+ * @param id {Number}
+ * @returns {Promise}
+ */
 exports.getAverageWpm = id => {
   return Test.findOne({
     attributes: [[Sequelize.fn('AVG', Sequelize.col('wpm')), 'average']],
@@ -27,6 +49,15 @@ exports.getAverageWpm = id => {
   .then(res => { return _.get(res, 'dataValues.average'); });
 };
 
+/**
+ * Update a user with his new github infos or create one.
+ *
+ * @param githubId {Number} Github user identifier
+ * @param name {String}
+ * @param avatar {String}
+ * @param token {String} Github user token
+ * @returns {Promise}
+ */
 exports.updateOrCreate = (githubId, name, avatar, token) => {
 
   return exports.getByGithub(githubId)
@@ -45,6 +76,16 @@ exports.updateOrCreate = (githubId, name, avatar, token) => {
 
 };
 
+/**
+ * Create a new test result for a user.
+ *
+ * @param test {Object}
+ * @param test.wpm {Number}
+ * @param test.accuracy {Number}
+ * @param test.textId {Number}
+ * @param test.userId {Number}
+ * @returns {Promise}
+ */
 exports.newResult = test => {
 
   if (!test.wpm || !test.accuracy || !test.textId || !test.userId) { throw new Error('Missing test data.'); }