RESTAPI: Add some JSDoc

So we can have a decent REST API documentation generated.

1 files changed, 63 insertions, 0 deletions

diff --git a/models/checklists.js b/models/checklists.js
index 425a10b2..a372fafa 100644
--- a/models/checklists.js
+++ b/models/checklists.js
@@ -1,18 +1,33 @@
 Checklists = new Mongo.Collection('checklists');
 
+/**
+ * A Checklist
+ */
 Checklists.attachSchema(new SimpleSchema({
   cardId: {
+    /**
+     * The ID of the card the checklist is in
+     */
     type: String,
   },
   title: {
+    /**
+     * the title of the checklist
+     */
     type: String,
     defaultValue: 'Checklist',
   },
   finishedAt: {
+    /**
+     * When was the checklist finished
+     */
     type: Date,
     optional: true,
   },
   createdAt: {
+    /**
+     * Creation date of the checklist
+     */
     type: Date,
     denyUpdate: false,
     autoValue() { // eslint-disable-line consistent-return
@@ -24,6 +39,9 @@ Checklists.attachSchema(new SimpleSchema({
     },
   },
   sort: {
+    /**
+     * sorting value of the checklist
+     */
     type: Number,
     decimal: true,
   },
@@ -128,6 +146,15 @@ if (Meteor.isServer) {
 }
 
 if (Meteor.isServer) {
+  /**
+   * @operation get_all_checklists
+   * @summary Get the list of checklists attached to a card
+   *
+   * @param {string} boardId the board ID
+   * @param {string} cardId the card ID
+   * @return_type [{_id: string,
+   *                title: string}]
+   */
   JsonRoutes.add('GET', '/api/boards/:boardId/cards/:cardId/checklists', function (req, res) {
     Authentication.checkUserId( req.userId);
     const paramCardId = req.params.cardId;
@@ -149,6 +176,22 @@ if (Meteor.isServer) {
     }
   });
 
+  /**
+   * @operation get_checklist
+   * @summary Get a checklist
+   *
+   * @param {string} boardId the board ID
+   * @param {string} cardId the card ID
+   * @param {string} checklistId the ID of the checklist
+   * @return_type {cardId: string,
+   *               title: string,
+   *               finishedAt: string,
+   *               createdAt: string,
+   *               sort: number,
+   *               items: [{_id: string,
+   *                        title: string,
+   *                        isFinished: boolean}]}
+   */
   JsonRoutes.add('GET', '/api/boards/:boardId/cards/:cardId/checklists/:checklistId', function (req, res) {
     Authentication.checkUserId( req.userId);
     const paramChecklistId = req.params.checklistId;
@@ -173,6 +216,15 @@ if (Meteor.isServer) {
     }
   });
 
+  /**
+   * @operation new_checklist
+   * @summary create a new checklist
+   *
+   * @param {string} boardId the board ID
+   * @param {string} cardId the card ID
+   * @param {string} title the title of the new checklist
+   * @return_type {_id: string}
+   */
   JsonRoutes.add('POST', '/api/boards/:boardId/cards/:cardId/checklists', function (req, res) {
     Authentication.checkUserId( req.userId);
 
@@ -204,6 +256,17 @@ if (Meteor.isServer) {
     }
   });
 
+  /**
+   * @operation delete_checklist
+   * @summary Delete a checklist
+   *
+   * @description The checklist will be removed, not put in the recycle bin.
+   *
+   * @param {string} boardId the board ID
+   * @param {string} cardId the card ID
+   * @param {string} checklistId the ID of the checklist to remove
+   * @return_type {_id: string}
+   */
   JsonRoutes.add('DELETE', '/api/boards/:boardId/cards/:cardId/checklists/:checklistId', function (req, res) {
     Authentication.checkUserId( req.userId);
     const paramChecklistId = req.params.checklistId;