From 91013a681400f377c737029682991e5d745dd060 Mon Sep 17 00:00:00 2001 From: samr28 Date: Wed, 20 Dec 2017 18:06:43 -0600 Subject: [PATCH] Documentation --- scripts/agenda.js | 68 +++++++++++++++++++++++++++++++++++------ scripts/hubot-agenda.js | 15 +++++---- scripts/utils.js | 11 ++++++- 3 files changed, 76 insertions(+), 18 deletions(-) diff --git a/scripts/agenda.js b/scripts/agenda.js index dd1ce2b..d9480d2 100644 --- 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,21 +141,31 @@ 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)) { @@ -164,24 +173,47 @@ function getBrainData(robot) { } 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 index a96fe1d..ec221b3 100644 --- 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 index c915399..f0a59bc 100644 --- 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 */