From dc56ba6ba82826d43ac89e85d6bbe7e11c1a0bdc Mon Sep 17 00:00:00 2001
From: Cole Furfaro-Strode <colestrode@gmail.com>
Date: Tue, 19 Jul 2016 22:07:06 -0400
Subject: [PATCH] adds correct jsdoc style docs

---
 lib/Slack_web_api.js | 57 ++++++++++++++++++++++++++++++--------------
 1 file changed, 39 insertions(+), 18 deletions(-)

diff --git a/lib/Slack_web_api.js b/lib/Slack_web_api.js
index 48562fe04..2dfca019b 100755
--- a/lib/Slack_web_api.js
+++ b/lib/Slack_web_api.js
@@ -1,7 +1,16 @@
 var request = require('request');
 
+/**
+ * Does nothing. Takes no params, returns nothing. It's a no-op!
+ */
 function noop() {}
 
+/**
+ * Returns an interface to the Slack API in the context of the given bot
+ * @param {Object} bot The botkit bot object
+ * @param {Object} config A config containing auth credentials.
+ * @returns {Object} A callback-based Slack API interface.
+ */
 module.exports = function(bot, config) {
     var slack_api = {
         api_url: 'https://slack.com/api/'
@@ -79,28 +88,40 @@ module.exports = function(bot, config) {
         'users.setActive'
     ];
 
-    slack_api.callAPI = function(command, options, cb) {
-        if (!options.token) {
-            options.token = config.token;
+    /**
+     * Calls Slack using a Token for authentication/authorization
+     * @param {string} command The Slack API command to call
+     * @param {Object} data The data to pass to the API call
+     * @param {function} cb A NodeJS-style callback
+     */
+    slack_api.callAPI = function(command, data, cb) {
+        if (!data.token) {
+            data.token = config.token;
         }
 
-        bot.debug(command, options);
-        postForm(slack_api.api_url + command, options, cb);
+        bot.debug(command, data);
+        postForm(slack_api.api_url + command, data, cb);
     };
 
-    slack_api.callAPIWithoutToken = function(command, options, cb) {
-        if (!options.client_id) {
-            options.client_id = bot.config.clientId;
+    /**
+     * Calls Slack using OAuth for authentication/authorization
+     * @param {string} command The Slack API command to call
+     * @param {Object} data The data to pass to the API call
+     * @param {function} cb A NodeJS-style callback
+     */
+    slack_api.callAPIWithoutToken = function(command, data, cb) {
+        if (!data.client_id) {
+            data.client_id = bot.config.clientId;
         }
-        if (!options.client_secret) {
-            options.client_secret = bot.config.clientSecret;
+        if (!data.client_secret) {
+            data.client_secret = bot.config.clientSecret;
         }
-        if (!options.redirect_uri) {
-            options.redirect_uri = bot.config.redirectUri;
+        if (!data.redirect_uri) {
+            data.redirect_uri = bot.config.redirectUri;
         }
 
         // DON'T log options: that could expose the client secret!
-        postForm(slack_api.api_url + command, options, cb);
+        postForm(slack_api.api_url + command, data, cb);
     };
 
 
@@ -141,11 +162,11 @@ module.exports = function(bot, config) {
 
     /**
      * Makes a POST request as a form to the given url with the options as data
-     * @param url
-     * @param options
-     * @param cb
+     * @param {string} url The URL to POST to
+     * @param {Object} formData The data to POST as a form
+     * @param {function=} cb An optional NodeJS style callback when the POST completes or errors out.
      */
-    function postForm(url, options, cb) {
+    function postForm(url, formData, cb) {
         cb = cb || noop;
 
         bot.log('** API CALL: ' + url);
@@ -165,6 +186,6 @@ module.exports = function(bot, config) {
                 return cb(json.error, json);
             }
             return cb(error || new Error('Invalid response'));
-        }).form(options);
+        }).form(formData);
     }
 };