Add Comments (#4)

[rbdr/dasein] / lib / twitter_helper.js

diff --git a/lib/twitter_helper.js b/lib/twitter_helper.js
index 3ab51fa7bd516521b7d2dc4489d7bdb9caaf59ea..6edf030d0b3775b17997f7a0ba1473b19d83ecd1 100644 (file)
--- a/lib/twitter_helper.js
+++ b/lib/twitter_helper.js
@@ -12,6 +12,16 @@ internals.kVerifyCredentialsUrl = 'https://api.twitter.com/1.1/account/verify_cr
 internals.kOauthVersion = '1.0A';
 internals.kOauthSignatureMethod = 'HMAC-SHA1';
 
+/**
+ * Helper to communicate with the twitter API
+ *
+ * @class TwitterHelper
+ * @param {Dasein.tTwitterConfiguration} config the configuration to
+ * initialize the twitter API
+ * @see {@link https://dev.twitter.com/web/sign-in/implementing|Implementing
+ * Sign in with Twitter}
+ *
+ */
 module.exports = internals.TwitterHelper = class TwitterHelper {
 
   constructor(config) {
@@ -27,6 +37,14 @@ module.exports = internals.TwitterHelper = class TwitterHelper {
     );
   }
 
+  /**
+   * Calls the API to get a request token.
+   *
+   * @function getRequestToken
+   * @memberof TwitterHelper
+   * @instance
+   * @return {Promise<TwitterHelper.tRequestToken>} the request token response
+   */
   getRequestToken() {
 
     const self = this;
@@ -36,6 +54,15 @@ module.exports = internals.TwitterHelper = class TwitterHelper {
       const getOAuthRequestToken = Pify(self._oAuth.getOAuthRequestToken.bind(self._oAuth), { multiArgs: true });
       const [oAuthToken, oAuthTokenSecret] = yield getOAuthRequestToken();
 
+      /**
+       * The request token and secret pair from the twitter API
+       *
+       * @memberof TwitterHelper
+       * @typedef {object} tRequestToken
+       * @property {string} oAuthToken The oAuth request token
+       * @property {string} oAuthTokenSecret The oAuth request token
+       * secret
+       */
       return {
         oAuthToken,
         oAuthTokenSecret
@@ -43,6 +70,17 @@ module.exports = internals.TwitterHelper = class TwitterHelper {
     });
   }
 
+  /**
+   * Calls the API to get an access token
+   *
+   * @function getAccessToken
+   * @memberof TwitterHelper
+   * @instance
+   * @param {string} oAuthToken An oAuth request token
+   * @param {string} oAuthVerifier An oAuth verifier sent from the
+   * twitter callback
+   * @return {Promise<TwitterHelper.tAccessToken>} the acess token response
+   */
   getAccessToken(oAuthToken, oAuthVerifier) {
 
     const self = this;
@@ -54,6 +92,15 @@ module.exports = internals.TwitterHelper = class TwitterHelper {
                                                                                    '',
                                                                                    oAuthVerifier);
 
+      /**
+       * The access token and secret pair from the twitter API
+       *
+       * @memberof TwitterHelper
+       * @typedef {object} tAccessToken
+       * @property {string} oAuthAccessToken The oAuth access token
+       * @property {string} oAuthAccessTokenSecret The oAuth access token
+       * secret
+       */
       return {
         oAuthAccessToken,
         oAuthAccessTokenSecret
@@ -61,6 +108,17 @@ module.exports = internals.TwitterHelper = class TwitterHelper {
     });
   }
 
+  /**
+   * Gets a user object from twitter
+   *
+   * @function getUser
+   * @memberof TwitterHelper
+   * @instance
+   * @param {string} oAuthAccessToken An oAuth access token
+   * @param {string} oAuthAccessTokenSecret An oAuth access token secret
+   * @return {Promise<external:TwitterUser>} the user object from
+   * twitter
+   */
   getUser(oAuthAccessToken, oAuthAccessTokenSecret) {
 
     const self = this;
@@ -72,6 +130,12 @@ module.exports = internals.TwitterHelper = class TwitterHelper {
                                        oAuthAccessToken,
                                        oAuthAccessTokenSecret);
 
+      /**
+       * The twitter user from the API
+       * @external TwitterUser
+       * @see {@link https://dev.twitter.com/overview/api/users|Twitter
+       * Api Overview: Users}
+       */
       return JSON.parse(userResponse);
     });
   }