RESTAPI: Add some JSDoc

So we can have a decent REST API documentation generated.

1 files changed, 68 insertions, 0 deletions

diff --git a/models/lists.js b/models/lists.js
index b99fe8f5..0e1ba801 100644
--- a/models/lists.js
+++ b/models/lists.js
@@ -1,10 +1,19 @@
 Lists = new Mongo.Collection('lists');
 
+/**
+ * A list (column) in the Wekan board.
+ */
 Lists.attachSchema(new SimpleSchema({
   title: {
+    /**
+     * the title of the list
+     */
     type: String,
   },
   archived: {
+    /**
+     * is the list archived
+     */
     type: Boolean,
     autoValue() { // eslint-disable-line consistent-return
       if (this.isInsert && !this.isSet) {
@@ -13,9 +22,15 @@ Lists.attachSchema(new SimpleSchema({
     },
   },
   boardId: {
+    /**
+     * the board associated to this list
+     */
     type: String,
   },
   createdAt: {
+    /**
+     * creation date
+     */
     type: Date,
     autoValue() { // eslint-disable-line consistent-return
       if (this.isInsert) {
@@ -26,12 +41,18 @@ Lists.attachSchema(new SimpleSchema({
     },
   },
   sort: {
+    /**
+     * is the list sorted
+     */
     type: Number,
     decimal: true,
     // XXX We should probably provide a default
     optional: true,
   },
   updatedAt: {
+    /**
+     * last update of the list
+     */
     type: Date,
     optional: true,
     autoValue() { // eslint-disable-line consistent-return
@@ -43,19 +64,31 @@ Lists.attachSchema(new SimpleSchema({
     },
   },
   wipLimit: {
+    /**
+     * WIP object, see below
+     */
     type: Object,
     optional: true,
   },
   'wipLimit.value': {
+    /**
+     * value of the WIP
+     */
     type: Number,
     decimal: false,
     defaultValue: 1,
   },
   'wipLimit.enabled': {
+    /**
+     * is the WIP enabled
+     */
     type: Boolean,
     defaultValue: false,
   },
   'wipLimit.soft': {
+    /**
+     * is the WIP a soft or hard requirement
+     */
     type: Boolean,
     defaultValue: false,
   },
@@ -212,6 +245,14 @@ if (Meteor.isServer) {
 
 //LISTS REST API
 if (Meteor.isServer) {
+  /**
+   * @operation get_all_lists
+   * @summary Get the list of Lists attached to a board
+   *
+   * @param {string} boardId the board ID
+   * @return_type [{_id: string,
+   *           title: string}]
+   */
   JsonRoutes.add('GET', '/api/boards/:boardId/lists', function (req, res) {
     try {
       const paramBoardId = req.params.boardId;
@@ -235,6 +276,14 @@ if (Meteor.isServer) {
     }
   });
 
+  /**
+   * @operation get_list
+   * @summary Get a List attached to a board
+   *
+   * @param {string} boardId the board ID
+   * @param {string} listId the List ID
+   * @return_type Lists
+   */
   JsonRoutes.add('GET', '/api/boards/:boardId/lists/:listId', function (req, res) {
     try {
       const paramBoardId = req.params.boardId;
@@ -253,6 +302,14 @@ if (Meteor.isServer) {
     }
   });
 
+  /**
+   * @operation new_list
+   * @summary Add a List to a board
+   *
+   * @param {string} boardId the board ID
+   * @param {string} title the title of the List
+   * @return_type {_id: string}
+   */
   JsonRoutes.add('POST', '/api/boards/:boardId/lists', function (req, res) {
     try {
       Authentication.checkUserId( req.userId);
@@ -276,6 +333,17 @@ if (Meteor.isServer) {
     }
   });
 
+  /**
+   * @operation delete_list
+   * @summary Delete a List
+   *
+   * @description This **deletes** a list from a board.
+   * The list is not put in the recycle bin.
+   *
+   * @param {string} boardId the board ID
+   * @param {string} listId the ID of the list to remove
+   * @return_type {_id: string}
+   */
   JsonRoutes.add('DELETE', '/api/boards/:boardId/lists/:listId', function (req, res) {
     try {
       Authentication.checkUserId( req.userId);