better documented StudentController.update_picto and StudentController.update_category

sails/src/api/controllers/StudentController.js

@@ -914,9 +914,41 @@ module.exports = {
     });
     });
   },
   },
 
 
-  // update action
-  // update picto atributes for a studentPicto
-  //
+  /*
+  * Updates the attributes of a picto related to student, i.e. stu_picto records
+  * @param {request} req {
+  *   'id_stu': <student ID>,
+  *   'id_pic': <picto ID>,
+  *   'attributes': <object>
+  * }
+  *
+  * or
+  *
+  * @param {request} req {
+  *   'id_stuPicto': <stuPicto ID>,
+  *   'attributes': <object>
+  * }
+  *
+  * @param {response} res {
+  *     id: <stu_picto ID>,
+  *     student: <student ID>,
+  *     attributes: {
+  *       id_cat: categoryId or null,
+  *       coord_x: 1 .. 5 or null,
+  *       coord_y: 1 .. 10 or null,
+  *       free_category_coord_x: 0 .. 4 or null,
+  *       free_category_coord_y: 0 .. 9 or null,
+  *       status: '[invisible]/enabled/disabled',
+  *       highlight: true/[false],
+  *       legend: true/[false],
+  *       legend_size: '[small]/large',
+  *       expression: 'custom expression',
+  *       color: any valid HEX color or [null]
+  *     }
+  *   },
+  * }
+  *
+  */
   update_picto: function (req, res) {
   update_picto: function (req, res) {
     var params = req.allParams();
     var params = req.allParams();
 
 
@@ -952,11 +984,24 @@ module.exports = {
   *   'prev_id_stu_pic': <ID of previous category entry in stu_picto>,
   *   'prev_id_stu_pic': <ID of previous category entry in stu_picto>,
   *   'new_id_pic': <ID of the picto to be the replacement>
   *   'new_id_pic': <ID of the picto to be the replacement>
   * }
   * }
+  *
   * @param {response} res {
   * @param {response} res {
-  *   'id_stu_pic': <id of the new category in stu_picto>,
-  *   'attributes': <attributes of the new category picto>,
-  *   'picto': <picto information used as new category>
+  *     id: <stu_picto ID>,
+  *     student: <student ID>,
+  *     attributes: {
+  *       id_cat: categoryId or null,
+  *       coord_x: 1 .. 5 or null,
+  *       coord_y: 1 .. 10 or null,
+  *       free_category_coord_x: 0 .. 4 or null,
+  *       free_category_coord_y: 0 .. 9 or null,
+  *       status: '[invisible]/enabled/disabled',
+  *       highlight: true/[false],
+  *       legend: true/[false],
+  *       legend_size: '[small]/large',
+  *       expression: 'custom expression',
+  *       color: any valid HEX color or [null]
   *     }
   *     }
+  *   },
   *
   *
   */
   */
   update_category: function (req, res) {
   update_category: function (req, res) {

sails/src/api/models/Student.js

@@ -556,6 +556,23 @@ module.exports = {
   * This method homogenizes the responses in HTTP requests and Websockets
   * This method homogenizes the responses in HTTP requests and Websockets
   * @param id_stu_pic {ID} stu_picto record id
   * @param id_stu_pic {ID} stu_picto record id
   * @param cb {function(err, result)} callback function
   * @param cb {function(err, result)} callback function
+  * @return result {
+  *  id: <stu_picto ID>,
+  *  student: <student ID>,
+  *  attributes: {
+  *     id_cat: categoryId or null,
+  *     coord_x: 1 .. 5 or null,
+  *     coord_y: 1 .. 10 or null,
+  *     free_category_coord_x: 0 .. 4 or null,
+  *     free_category_coord_y: 0 .. 9 or null,
+  *     status: '[invisible]/enabled/disabled',
+  *     highlight: true/[false],
+  *     legend: true/[false],
+  *     legend_size: '[small]/large',
+  *     expression: 'custom expression',
+  *     color: any valid HEX color or [null]
+  *  }
+  * }
   */
   */
   pictoInfo: function(id_stu_pic, cb) {
   pictoInfo: function(id_stu_pic, cb) {
     StuPicto.findOne(id_stu_pic)
     StuPicto.findOne(id_stu_pic)