redd 0.4.3 → 0.5.0

data/lib/redd/client/authenticated/multis.rb

@@ -1,8 +1,8 @@
 module Redd
   module Client
     class Authenticated
+      # Methods to interact with multis (groups of subreddits).
       module Multis
-        
       end
     end
   end

data/lib/redd/client/authenticated/private_messages.rb

@@ -1,32 +1,78 @@
 module Redd
   module Client
     class Authenticated
+      # Methods for sending and reading private messages
       module PrivateMessages
+        # Block the sender of the message from sending any more.
+        #
+        # @param message [Redd::Object::PrivateMessage, String] The message
+        #   whose sender to block.
         def block_message(message)
           fullname = extract_fullname(message)
           post "/api/block", id: fullname
         end
 
+        # Compose a message to a person or the moderators of a subreddit.
+        #
+        # @param to [Redd::Object::User, Redd::Object::Subreddit, String] The
+        #   thing to send a message to.
+        # @param subject [String] The subject of the message.
+        # @param text [String] The message text.
+        # @param captcha [String] A possible captcha result to send if one
+        #   is required.
+        # @param identifier [String] The identifier for the captcha if one
+        #   is required.
         def compose_message(to, subject, text, captcha = nil, identifier = nil)
-          params = {
-            api_type: "json", to: to.to_s, subject: subject, text: text
-          }
+          params[:to] = 
+            case to
+            when Redd::Object::User
+              to.name
+            when Redd::Object::Subreddit
+              to.display_name
+            when String
+              to
+            end
+
+          params = {api_type: "json", subject: subject, text: text}
           params << {captcha: captcha, iden: identifier} if captcha
 
           post "/api/compose", params
         end
 
+        # Mark a message as read.
+        #
+        # @param message [Redd::Object::PrivateMessage, String] The message
+        #   to mark as read.
         def mark_as_read(message)
           fullname = extract_fullname(message)
           post "/api/read_message", id: fullname
         end
 
+        # Mark a message as unread.
+        #
+        # @param message [Redd::Object::PrivateMessage, String] The message
+        #   to mark as unread.
         def mark_as_unread(message)
           fullname = extract_fullname(message)
           post "/api/unread_message", id: fullname
         end
 
-        def messages(category = "inbox", params = {})
+        # Return a list of a user's private messages.
+        #
+        # @param category [String] The category of messages to view.
+        # @param mark [Boolean] Whether to remove the orangered from the
+        #   user's inbox. 
+        # @param params [Hash] A list of params to send with the request.
+        # @option params [String] :after Return results after the given
+        #   fullname.
+        # @option params [String] :before Return results before the given
+        #   fullname.
+        # @option params [Integer] :count (0) The number of items already seen
+        #   in the listing.
+        # @option params [1..100] :limit (25) The maximum number of things to
+        #   return.
+        def messages(category = "inbox", mark = false, params = {})
+          params[:mark] = mark
           object_from_response :get, "/message/#{category}.json", params
         end
       end

data/lib/redd/client/authenticated/subreddits.rb

@@ -1,15 +1,38 @@
 module Redd
   module Client
     class Authenticated
+      # Methods to interact with subreddits
       module Subreddits
+        # Subscribe to a subreddit.
+        #
+        # @param subreddit [Redd::Object::Subreddit, String] The subreddit to
+        #   subscribe to.
         def subscribe(subreddit)
           edit_subscription(:sub, subreddit)
         end
 
+        # Unsubscribe from a subreddit.
+        #
+        # @param subreddit [Redd::Object::Subreddit, String] The subreddit to
+        #   unsubscribe from.
         def unsubscribe(subreddit)
           edit_subscription(:unsub, subreddit)
         end
 
+        # Get a listing of subreddits.
+        #
+        # @param where [:popular, :new, :subscriber, :contributor, :moderator]
+        #   The order of subreddits to return.
+        # @param params [Hash] A list of params to send with the request.
+        # @option params [String] :after Return results after the given
+        #   fullname.
+        # @option params [String] :before Return results before the given
+        #   fullname.
+        # @option params [Integer] :count (0) The number of items already seen
+        #   in the listing.
+        # @option params [1..100] :limit (25) The maximum number of things to
+        #   return.
+        # @return [Redd::Object::Listing] A listing of subreddits.
         def get_subreddits(where = :subscriber, params = {})
           path =
             if [:popular, :new].include?(where)
@@ -22,6 +45,11 @@ module Redd
 
         private
 
+        # Subscribe or unsubscribe to a subreddit.
+        #
+        # @param action [:sub, :unsub] The type of action to perform.
+        # @param subreddit [Redd::Object::Subreddit, String] The subreddit to
+        #   perform the action on.
         def edit_subscription(action, subreddit)
           fullname = extract_fullname(subreddit)
           post "/api/subscribe", action: action, sr: fullname

data/lib/redd/client/authenticated/users.rb

@@ -1,8 +1,8 @@
 module Redd
   module Client
     class Authenticated
+      # Methods to interact with other users
       module Users
-        
       end
     end
   end

data/lib/redd/client/authenticated/wiki.rb

@@ -1,8 +1,8 @@
 module Redd
   module Client
     class Authenticated
+      # Methods to interact with wiki pages
       module Wiki
-        
       end
     end
   end

data/lib/redd/client/oauth2.rb

@@ -44,14 +44,14 @@ module Redd
 
       private
 
-      def connection(access_token = @access.access_token)
+      def connection
         @connection ||= Faraday.new(url: api_endpoint) do |faraday|
           faraday.use Faraday::Request::UrlEncoded
           faraday.use Redd::Response::RaiseError
           faraday.use Redd::Response::ParseJson
           faraday.adapter Faraday.default_adapter
 
-          faraday.headers["Authorization"] = "bearer #{access_token}"
+          faraday.headers["Authorization"] = "bearer #{@access.access_token}"
           faraday.headers["User-Agent"] = "Redd/Ruby, v#{Redd::VERSION}"
         end
       end

data/lib/redd/client/oauth2/authorization.rb

@@ -3,40 +3,73 @@ require "redd/oauth2_access"
 module Redd
   module Client
     class OAuth2
+      # Methods for obtaining an access token
       module Authorization
-        def auth_url(scope = ["identity"], duration = "temporary", state = "x")
+        # Build an authorization url to redirect the user to.
+        #
+        # @param scopes [Array<String>] The access scopes to request from the
+        #   user.
+        # @param duration [:temporary, :permanent] The duration of your access
+        #   to the user's account.
+        # @param state [String] A random string to check later.
+        # @return [String] The url.
+        #
+        # @note The access tokens from both duration last only an hour, but you
+        #   also get a refresh token when the duration is permanent.
+        # @note You may be tempted to let the state remain "x", but seriously,
+        #   use this; it helps prevent against CSRF attacks.
+        def auth_url(scopes = ["identity"], duration = :temporary, state = "x")
           path = "https://ssl.reddit.com/api/v1/authorize"
+          scope = scopes.is_a?(Array) ? scopes.join(",") : scopes
           query = {
             client_id: @client_id,
             redirect_uri: @redirect_uri,
             response_type: "code",
             state: state,
-            scope: scope.join(","),
+            scope: scope,
             duration: duration
           }
           string_query = query.map { |key, value| "#{key}=#{value}" }.join("&")
-
           "#{path}?#{string_query}"
         end
 
-        def request_access_token(code, set_access = true)
+        # Request an access token from the code that is sent with the redirect.
+        #
+        # @param code [String] The code that was sent in the GET request.
+        # @param set_access [Boolean] Whether to automatically use this token
+        #   for all future requests with this client.
+        # @return [Redd::OAuth2Access] A package of the necessary information
+        #   to access the user's information.
+        def request_access(code, set_access = true)
           response = auth_connection.post "/api/v1/access_token",
-            grant_type: "authorization_code", code: code,
-            redirect_uri: @redirect_uri
+                                          grant_type: "authorization_code",
+                                          code: code,
+                                          redirect_uri: @redirect_uri
 
           access = Redd::OAuth2Access.new(response.body)
           @access = access if set_access
           access
         end
 
-        def refresh_access_token(access = nil, set_access = true)
-          refresh_token = extract_attribute(access, :refresh_token)
+        # Obtain a new access token using a refresh token.
+        #
+        # @param token [Redd::OAuth2Access, String, nil] The refresh token or
+        #   OAuth2Access. If none is provided, it'll refresh the one the client
+        #   is currently using.
+        # @param set_access [Boolean] Whether to automatically use this token
+        #   for all future requests with this client.
+        # @return [Redd::OAuth2Access] The refreshed information.
+        def refresh_access(token = nil, set_access = true)
+          refresh_token = extract_attribute(token, :refresh_token)
           response = auth_connection.post "/api/v1/access_token",
-            grant_type: "refresh_token", refresh_token: refresh_token
+                                          grant_type: "refresh_token",
+                                          refresh_token: refresh_token
 
-          case access
-          when Redd::OAuth2Access
+          case token
+          when nil
             access.refresh(response.body)
+          when Redd::OAuth2Access
+            token.refresh(response.body)
           when ::String
             new_access = Redd::OAuth2Access.new(response.body)
             @access = new_access if set_access

data/lib/redd/client/oauth2/identity.rb

@@ -1,7 +1,11 @@
 module Redd
   module Client
     class OAuth2
+      # Methods to interact with the user logged-in via OAuth2
       module Identity
+        # @return [Redd::Object::User] The logged-in user.
+        # @note This overrides the Authenticated class's method, since that
+        #   method doesn't apply here but does the same thing.
         def me
           response = get "/api/v1/me.json"
           object_from_body kind: "t2", data: response

data/lib/redd/client/unauthenticated/account.rb

@@ -1,10 +1,22 @@
 module Redd
   module Client
     class Unauthenticated
+      # Methods for managing accounts.
       module Account
+        # Login to the reddit account.
+        #
+        # @param username [String] The username.
+        # @param password [String] The password.
+        # @param remember [Boolean] Indicates whether you intend to use the
+        #   returned cookie for a long time.
+        # @param options [Hash] The options to create an instance of
+        #   {Redd::Client::Authenticated}.
         def login(username, password, remember = false, options = {})
           response = post "/api/login",
-            api_type: "json", user: username, passwd: password, rem: remember
+                          api_type: "json",
+                          user: username,
+                          passwd: password,
+                          rem: remember
           data = response[:json][:data]
 
           require "redd/client/authenticated"

data/lib/redd/client/unauthenticated/captcha.rb

@@ -1,16 +1,23 @@
 module Redd
   module Client
     class Unauthenticated
+      # Methods to get captchas.
+      # Many things like sending messages and posting links require captchas.
       module Captcha
+        # @return [Boolean] Whether a captcha is required for some API methods.
         def needs_captcha?
           get "/api/needs_captcha.json"
         end
 
+        # Create a new captcha identifier.
+        # @return [String] The identifier.
         def new_captcha
           response = get "/api/new_captcha", api_type: "json"
           response[:json][:data][:iden]
         end
 
+        # @param identifier [String] The captcha identifier.
+        # @return The url for the captcha image.
         def captcha_url(identifier)
           "http://www.reddit.com/captcha/#{identifier}.png"
         end

data/lib/redd/client/unauthenticated/links_comments.rb

@@ -2,20 +2,37 @@ module Redd
   module Client
     class Unauthenticated
       module LinksComments
+        # @param params [Hash] A hash of parameters to send to reddit.
+        # @option params [String] :id The fullname of a thing.
+        # @option params [String] :url The url of a thing. If an id is also
+        #   provided, the id will take precedence.
+        # @return [Redd::Object::Submission, Redd::Object::Comment] The object.
+        #
         # @note Reddit does accept a subreddit, but with fullnames and urls, I
         #   assumed that was unnecessary.
         def get_info(params = {})
-          object_from_response :get, "/api/info.json", params
+          object = object_from_response :get, "/api/info.json", params
+          object.first
         end
 
+        # Get the comments for a submission.
+        #
+        # @param submission [String, Redd::Object::Submission] The submission
+        #   to get the comments for.
+        # @return [Redd::Object::Listing] A listing of comments.
         def submission_comments(submission)
           id = extract_id(submission)
           comments_from_response :get, "/comments/#{id}.json"
         end
 
+        # Get the replies for a comment.
+        #
+        # @param comment [String, Redd::Object::Submission] The comment to get
+        #   the replies for.
+        # @return [Redd::Object::Listing] A listing of comments.
         def get_replies(comment)
           replies = comment.attributes[:replies]
-          return [] unless replies.is_a?(Hash) and replies.has_key?(:kind)
+          return [] unless replies.is_a?(Hash) && replies.key?(:kind)
           object_from_body(replies)
         end
 
@@ -30,8 +47,10 @@ module Redd
               get_info(id: parent_id).first.link_id
             end
 
-          response = post "/api/morechildren", api_type: "json",
-            link_id: link_id, children: morecomments.children.join(",")
+          response = post "/api/morechildren",
+                          api_type: "json",
+                          link_id: link_id,
+                          children: morecomments.children.join(",")
           comments = response[:json][:data][:things]
 
           # No idea how to increase the depth of the comments.

data/lib/redd/client/unauthenticated/listing.rb

@@ -1,38 +1,56 @@
 module Redd
   module Client
     class Unauthenticated
+      # Methods that return a listing
       module Listing
-        def by_id(*fullnames)
-          names = fullnames.join(",")
-          object_from_response :get,  "/by_id/#{names}.json"
+        # Get an object based on its id.
+        #
+        # @param fullname [String] The fullname of a thing.
+        # @return [Redd::Object] The object with the id.
+        def by_id(fullname)
+          object_from_response :get, "/by_id/#{fullname}.json"
         end
 
-        def get_hot(*args)
-          get_listing(:hot, *args)
-        end
-
-        def get_new(*args)
-          get_listing(:new, *args)
-        end
-
-        def get_random(*args)
-          get_listing(:random, *args)
-        end
-
-        def get_top(*args)
-          get_listing(:top, *args)
-        end
-
-        def get_controversial(*args)
-          get_listing(:controversial, *args)
-        end
-
-        def get_comments(*args)
-          get_listing(:comments, *args)
+        # @!method get_hot
+        # @!method get_new
+        # @!method get_random
+        # @!method get_top
+        # @!method get_controversial
+        # @!method get_comments
+        #
+        # Get the appropriate listing.
+        # @param subreddit [Redd::Object::Subreddit] The subreddit to query.
+        # @param params [Hash] A list of params to send with the request.
+        #
+        # @see #get_listing
+        %w(hot new random top controversial comments).each do |sort|
+          define_method :"get_#{sort}" do |subreddit = nil, params = {}|
+            get_listing(sort, subreddit, params)
+          end
         end
 
         private
 
+        # Get the front page of reddit or a subreddit sorted by type.
+        #
+        # @param type [:hot, :new, :random, :top, :controversial, :comments]
+        #   The type of listing to return 
+        # @param subreddit [Redd::Object::Subreddit, String] The subreddit to
+        #   query.
+        # @param params [Hash] A list of params to send with the request.
+        # @option params [String] :after Return results after the given
+        #   fullname.
+        # @option params [String] :before Return results before the given
+        #   fullname.
+        # @option params [Integer] :count (0) The number of items already seen
+        #   in the listing.
+        # @option params [1..100] :limit (25) The maximum number of things to
+        #   return.
+        # @option params [:hour, :day, :week, :month, :year, :all] :t The
+        #   time period to consider when sorting.
+        # @return [Redd::Object::Listing] A listing of submissions or comments.
+        #
+        # @note The option :t only applies to the top and controversial sorts.
         def get_listing(type, subreddit = nil, params = {})
           name = extract_attribute(subreddit, :display_name) if subreddit