Documentation

samr28 · Dec 21, 2017 · 91013a6 · 91013a6
1 parent 31146cb
commit 91013a6
Show file tree

Hide file tree

Showing 3 changed files with 76 additions and 18 deletions.
diff --git a/scripts/agenda.js b/scripts/agenda.js
@@ -18,7 +18,6 @@ module.exports = {
   assign            : assign,
   unassign          : unAssign,
   setImportance     : setImportance,
-  formatAgenda      : formatAgenda,
   getAgenda         : getAgenda,
   getAgendaSlack    : getAgendaSlack,
   listAgendaChannel : listAgendaChannel
@@ -142,46 +141,79 @@ function setImportance(robot, id, importance) {
   return `Set item #${id} importance to ${importance}`;
 }
 
-function formatAgenda(agenda) {
-  if (!agenda || _.isNull(agenda)) return new Error('Empty agenda');
-  return { attachments : [{ text : agenda.sort().join('\n') }] };
-}
-
+/**
+ * Get the agenda from Redis
+ * @param  {Object} robot Hubot object
+ * @return {Object}       Agenda
+ */
 function getAgenda(robot) {
   if (getBrainData(robot).length < 1) {
     return new Error('Empty agenda');
   }
   return getBrainData(robot);
 }
+/**
+ * Get the number of items/length of the agenda
+ * @param  {Object} robot Hubot object
+ * @return {number}       Number of items in the agenda
+ */
 function getAgendaLength(robot) {
   return getAgenda(robot).length;
 }
 
+/**
+ * Get the data stored in the redis brain
+ * @param  {Object} robot Hubot object
+ * @return {Object}       Brain data
+ */
 function getBrainData(robot) {
   let brainData = robot.brain.get(REDIS_BRAIN_KEY);
   if (!brainData || _.isNull(brainData) || !_.isArray(brainData)) {
     return new Error('Invalid data from Redis brain.');
   }
   return brainData;
 }
+
+/**
+ * Set the brain data
+ * @param {Object} robot Hubot object
+ * @param {Object} value Brain data
+ */
 function setBrainData(robot, value) {
   return robot.brain.set(REDIS_BRAIN_KEY, value);
 }
-function clearBrainData(robot) {
-  return robot.brain.set(REDIS_BRAIN_KEY, []);
-}
+
+/**
+ * Add an item to the redis brain
+ * @param {Object} robot   Hubot object
+ * @param {Object} newData New item
+ */
 function addBrainData(robot, newData) {
   let data = getBrainData(robot);
   if (!data || !_.isArray(data)) return new Error('Data from Redis brain is not valid!');
   data.push(newData);
   return setBrainData(robot, data);
 }
+
+/**
+ * Update an entry in the brain
+ * @param  {Object} robot   Hubot object
+ * @param  {number} id      Item id
+ * @param  {Object} newData New object to replace the item with
+ */
 function updateBrainData(robot, id, newData) {
   let data = getBrainData(robot);
   if (!data || !_.isArray(data)) return new Error('Data from Redis brain is not valid!');
   data[id] = newData;
   return setBrainData(robot, data);
 }
+
+/**
+ * Remove an item by name
+ * @param  {Object} robot Hubot object
+ * @param  {String} name  Name of the item to remove
+ * @return {Error}        If an error occurred
+ */
 function removeBrainDataByName(robot, name) {
   let data = getBrainData(robot);
   if (!data || !_.isArray(data)) return new Error('Data from Redis brain is not valid!');
@@ -198,6 +230,13 @@ function removeBrainDataByName(robot, name) {
   console.dir(data);
   return setBrainData(robot, data);
 }
+
+/**
+ * Remove an item by id
+ * @param  {Object} robot Hubot Object
+ * @param  {number} id    Id of the item to remove
+ * @return {Error}        If an error occurred
+ */
 function removeBrainDataById(robot, id) {
   console.log(`removeBrainDataById - ID: ${id}`);
   let data = getBrainData(robot);
@@ -206,9 +245,20 @@ function removeBrainDataById(robot, id) {
   return setBrainData(robot, data);
 }
 
+/**
+ * List the agenda in a certain channel
+ * @param  {Object} robot   Hubot object
+ * @param  {String} channel Channel name
+ */
 function listAgendaChannel(robot, channel) {
   robot.messageRoom(channel, getAgendaSlack(robot));
 }
+
+/**
+ * Get the agenda and format it as a json payload for Slack
+ * @param  {Object} robot Hubot object
+ * @return {Object}       Agenda formatted as attachments
+ */
 function getAgendaSlack(robot) {
   let a = getAgenda(robot);
   if (utils.checkError(a)) return a;

diff --git a/scripts/hubot-agenda.js b/scripts/hubot-agenda.js
@@ -35,6 +35,8 @@ const SCHEDULE = true;
 module.exports = function (robot) {
   let version = require('../package.json').version;
   let startTime = new Date();
+
+  // Basic commands
   robot.respond(/(?:agenda )?add (.+)/i, function (msg) {
     add(robot, msg);
   });
@@ -45,6 +47,7 @@ module.exports = function (robot) {
     listAgenda(robot, msg);
   });
 
+  // Advanced commands
   robot.respond(/(?:agenda )?update (\d+) (.+)/i, function (msg) {
     update(robot, msg);
   });
@@ -57,7 +60,11 @@ module.exports = function (robot) {
   robot.respond(/(?:agenda )?set importance (\d+) (\w+)/i, function (msg) {
     importance(robot, msg);
   });
+  robot.respond(/(?:agenda )?set priority (\d+) (\w+)/i, function (msg) {
+    importance(robot, msg);
+  });
 
+  // Debug/info commands
   robot.respond(/(?:agenda )?-?v(?:ersion)?(?!.)/i, function (msg) {
     utils.logMsgData(msg, `v${version}`);
     msg.send(`AgendaBot v${version}`);
@@ -74,7 +81,6 @@ module.exports = function (robot) {
   console.log(`Bot v${version} started @ ${startTime}`);
   /**
    * Start the robot brain if it has not already been started
-   *
    * @param  {Object} robot  Hubot object
    */
   function initBrain() {
@@ -95,7 +101,6 @@ module.exports = function (robot) {
 
 /**
  * Add something to the agenda
- *
  * @param {Object}  robot   Hubot object
  * @param {Object}  msg     Incoming message
  */
@@ -107,7 +112,6 @@ function add(robot, msg) {
 
 /**
  * Remove something from the agenda
- *
  * @param {Object}  robot   Hubot object
  * @param {Object}  msg     Incoming message
  */
@@ -128,7 +132,6 @@ function rm(robot, msg) {
 
 /**
  * Send a message with the agenda
- *
  * @param {Object}  robot  Hubot object
  * @param {Object}  msg    Incoming message
  */
@@ -139,7 +142,6 @@ function listAgenda(robot, msg) {
 
 /**
  * Update one of the agenda items
- *
  * @param  {Object} robot Hubot object
  * @param  {Object} msg   Incoming message
  */
@@ -160,7 +162,6 @@ function update(robot, msg) {
 
 /**
  * Set the assignee of an item
- *
  * @param  {Object} robot Hubot object
  * @param  {Object} msg   Incoming message
  */
@@ -182,7 +183,6 @@ function assign(robot, msg) {
 }
 /**
  * Resets the assignee of an item
- *
  * @param  {Object} robot Hubot object
  * @param  {Object} msg   Incoming message
  */
@@ -200,7 +200,6 @@ function unassign(robot, msg) {
 }
 /**
  * Set the importance/color of an item
- *
  * @param  {Object} robot Hubot object
  * @param  {Object} msg   Incoming message
  */

diff --git a/scripts/utils.js b/scripts/utils.js
@@ -11,10 +11,20 @@ module.exports = {
   logMsgData          : logMsgData
 };
 
+/**
+ * Check if value is an error
+ * @param  {Unknown} value Value to check
+ * @return {boolean}       If value is an error
+ */
 function checkError(value) {
   return value instanceof Error;
 }
 
+/**
+ * Check if the user who sent the message is an admin
+ * @param  {Object}  msg Incoming message
+ * @return {boolean}     If the sender is an admin
+ */
 function checkUserSlackAdmin(msg) {
   return true;
   let user = msg.message.user;
@@ -23,7 +33,6 @@ function checkUserSlackAdmin(msg) {
 
 /**
  * Log message info and extraData
- *
  * @param {Object}  msg         Incoming message
  * @param {String}  extraData   Any extra data to log
  */