From ff467402c0c24981078f1f8e2b92b26b0d67d00a Mon Sep 17 00:00:00 2001
From: Benjamin Tissoires <benjamin.tissoires@redhat.com>
Date: Fri, 26 Oct 2018 07:27:24 +0200
Subject: RESTAPI: Add some JSDoc

So we can have a decent REST API documentation generated.
---
 models/cardComments.js | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

(limited to 'models/cardComments.js')

diff --git a/models/cardComments.js b/models/cardComments.js
index b6cb10fa..974c5ec9 100644
--- a/models/cardComments.js
+++ b/models/cardComments.js
@@ -1,19 +1,34 @@
 CardComments = new Mongo.Collection('card_comments');
 
+/**
+ * A comment on a card
+ */
 CardComments.attachSchema(new SimpleSchema({
   boardId: {
+    /**
+     * the board ID
+     */
     type: String,
   },
   cardId: {
+    /**
+     * the card ID
+     */
     type: String,
   },
   // XXX Rename in `content`? `text` is a bit vague...
   text: {
+    /**
+     * the text of the comment
+     */
     type: String,
   },
   // XXX We probably don't need this information here, since we already have it
   // in the associated comment creation activity
   createdAt: {
+    /**
+     * when was the comment created
+     */
     type: Date,
     denyUpdate: false,
     autoValue() { // eslint-disable-line consistent-return
@@ -26,6 +41,9 @@ CardComments.attachSchema(new SimpleSchema({
   },
   // XXX Should probably be called `authorId`
   userId: {
+    /**
+     * the author ID of the comment
+     */
     type: String,
     autoValue() { // eslint-disable-line consistent-return
       if (this.isInsert && !this.isSet) {
@@ -87,6 +105,16 @@ if (Meteor.isServer) {
 
 //CARD COMMENT REST API
 if (Meteor.isServer) {
+  /**
+   * @operation get_all_comments
+   * @summary Get all comments attached to a card
+   *
+   * @param {string} boardId the board ID of the card
+   * @param {string} cardId the ID of the card
+   * @return_type [{_id: string,
+   *                comment: string,
+   *                authorId: string}]
+   */
   JsonRoutes.add('GET', '/api/boards/:boardId/cards/:cardId/comments', function (req, res) {
     try {
       Authentication.checkUserId( req.userId);
@@ -111,6 +139,15 @@ if (Meteor.isServer) {
     }
   });
 
+  /**
+   * @operation get_comment
+   * @summary Get a comment on a card
+   *
+   * @param {string} boardId the board ID of the card
+   * @param {string} cardId the ID of the card
+   * @param {string} commentId the ID of the comment to retrieve
+   * @return_type CardComments
+   */
   JsonRoutes.add('GET', '/api/boards/:boardId/cards/:cardId/comments/:commentId', function (req, res) {
     try {
       Authentication.checkUserId( req.userId);
@@ -130,6 +167,16 @@ if (Meteor.isServer) {
     }
   });
 
+  /**
+   * @operation new_comment
+   * @summary Add a comment on a card
+   *
+   * @param {string} boardId the board ID of the card
+   * @param {string} cardId the ID of the card
+   * @param {string} authorId the user who 'posted' the comment
+   * @param {string} text the content of the comment
+   * @return_type {_id: string}
+   */
   JsonRoutes.add('POST', '/api/boards/:boardId/cards/:cardId/comments', function (req, res) {
     try {
       Authentication.checkUserId( req.userId);
@@ -160,6 +207,15 @@ if (Meteor.isServer) {
     }
   });
 
+  /**
+   * @operation delete_comment
+   * @summary Delete a comment on a card
+   *
+   * @param {string} boardId the board ID of the card
+   * @param {string} cardId the ID of the card
+   * @param {string} commentId the ID of the comment to delete
+   * @return_type {_id: string}
+   */
   JsonRoutes.add('DELETE', '/api/boards/:boardId/cards/:cardId/comments/:commentId', function (req, res) {
     try {
       Authentication.checkUserId( req.userId);
-- 
cgit v1.2.3-1-g7c22