redd 0.4.3 → 0.5.0

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

@@ -1,6 +1,7 @@
 module Redd
   module Client
     class Unauthenticated
+      # Methods to interact with /r/live threads
       module Live
       end
     end

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

@@ -1,14 +1,22 @@
 module Redd
   module Client
     class Unauthenticated
+      # Methods that deal with subreddit styles
       module Moderation
+        # @param subreddit [Redd::Object::Subreddit, String] The subreddit to
+        #   query.
+        # @return [String] The url for the subreddit's css stylesheet.
         def stylesheet_url(subreddit = nil)
+          name = extract_attribute(subreddit, :display_name)
           path = "/stylesheet"
-          path = path.prepend("/r/#{subreddit}") if subreddit
+          path = path.prepend("/r/#{name}") if subreddit
 
           get(path).headers[:location]
         end
 
+        # @param subreddit [Redd::Object::Subreddit, String] The subreddit to
+        #   query.
+        # @return [String] The css stylesheet for the subreddit.
         def stylesheet(subreddit = nil)
           get stylesheet_url(subreddit)
         end

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

@@ -1,15 +1,45 @@
 module Redd
   module Client
     class Unauthenticated
+      # Methods that deal with subreddits
       module Subreddits
+        # Return a Subreddit object from the title of a subreddit.
+        # @param title [String] The name of the subreddit.
+        # @return [Redd::Object::Subreddit]
         def subreddit(title)
           object_from_response :get, "/r/#{title}/about.json"
         end
 
+        # Get a list of subreddits sorted by the given parameter.
+        # @param where [:subscriber, :contributor, :moderator, :popular, :new]
+        #   The type of subreddits to look for.
+        # @param params [Hash] A hash of parameters 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 = :popular, params = {})
           object_from_response :get, "/subreddits/#{where}.json", params
         end
 
+        # Look for subreddits matching the given query.
+        #
+        # @param query [String] The search query.
+        # @param params [Hash] A hash of parameters 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 search_subreddits(query, params = {})
           params << {q: query}
           object_from_response :get, "/subreddits/search.json", params

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

@@ -11,6 +11,7 @@ require "redd/object/wiki_page"
 module Redd
   module Client
     class Unauthenticated
+      # Non-API methods that make life easier
       module Utilities
         def comment_stream(*args, &block)
           submission_stream(:comments, *args, &block)
@@ -23,7 +24,7 @@ module Redd
             objects = get_listing(listing, subreddit, params)
             unless objects.empty?
               # Run the loop for each of the new comments accessed.
-              # I should probably add it to some sort of Set to avoid duplicates.
+              # I should probably add it to a Set to avoid duplicates.
               objects.reverse_each { |object| block.call(object) }
               # Set the latest comment.
               params[:before] = objects.first.fullname
@@ -38,7 +39,7 @@ module Redd
           when ::String
             object
           else
-          	object.send(attribute)
+            object.send(attribute)
           end
         end
 
@@ -50,7 +51,8 @@ module Redd
           extract_attribute(object, :id)
         end
 
-        def object_from_kind(kind) # rubocop:disable Style/MethodLength
+        # rubocop:disable Style/MethodLength, Style/CyclomaticComplexity
+        def object_from_kind(kind)
           case kind
           when "Listing"
             Redd::Object::Listing
@@ -72,6 +74,7 @@ module Redd
             Redd::Thing
           end
         end
+        # rubocop:enable Style/MethodLength, Style/CyclomaticComplexity
 
         def objects_from_listing(thing)
           thing[:data][:children].map do |child|
@@ -80,7 +83,7 @@ module Redd
         end
 
         def object_from_body(body)
-          return nil unless body.is_a?(Hash) && body.has_key?(:kind)
+          return nil unless body.is_a?(Hash) && body.key?(:kind)
           object = object_from_kind(body[:kind])
 
           if object == Redd::Object::Listing

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

@@ -1,17 +1,31 @@
 module Redd
   module Client
     class Unauthenticated
+      # Methods to interact with subreddit wikis
       module Wiki
+        # Get a list of pages in the subreddit wiki.
+        # @param subreddit [Redd::Object::Subreddit, String] The subreddit to
+        #   look in.
+        # @return [Array] An array of wikipage titles.
         def get_wikipages(subreddit = nil)
+          name = extract_attribute(subreddit, :display_name)
+
           path = "/wiki/pages.json"
-          path.prepend("/r/#{subreddit}") if subreddit
+          path.prepend("/r/#{name}") if subreddit
           get(path)[:data]
         end
 
-        def wikipage(page, subreddit = nil, params = {})
+        # Get a wiki page.
+        # @param page [String] The title of the wiki page.
+        # @param subreddit [Redd::Object::Subreddit, String] The subreddit to
+        #   look in.
+        # @return [Redd::Object::WikiPage] A wiki page.
+        def wikipage(page, subreddit = nil)
+          name = extract_attribute(subreddit, :display_name)
+
           path = "/wiki/#{page}.json"
-          path.prepend("/r/#{subreddit}") if subreddit
-          object_from_response :get, path, params
+          path.prepend("/r/#{name}") if subreddit
+          object_from_response :get, path
         end
       end
     end

data/lib/redd/error.rb

@@ -1,6 +1,6 @@
 module Redd
+  # An error from reddit
   class Error < StandardError
-
     attr_reader :code
     attr_reader :headers
     attr_reader :body
@@ -12,8 +12,8 @@ module Redd
     end
 
     class << self
-      # @note I ripped off RedditKit.rb :|
-      def from_response(response) # rubocop:disable Style/CyclomaticComplexity Style/MethodLength
+      # rubocop:disable Style/CyclomaticComplexity, Style/MethodLength
+      def from_response(response)
         status = response[:status]
         body = parse_error(response[:body]).to_s
         case status
@@ -57,6 +57,7 @@ module Redd
           Redd::Error::TimedOut
         end
       end
+      # rubocop:enable Style/CyclomaticComplexity, Style/MethodLength
 
       def parse_error(body)
         return nil unless body.is_a?(Hash)
@@ -89,6 +90,7 @@ module Redd
 
     class PermissionDenied < Error; end
 
+    # Raised when the client needs to wait before making another request
     class RateLimited < Error
       attr_reader :time
 

data/lib/redd/oauth2_access.rb

@@ -1,17 +1,29 @@
 require "multi_json"
 
 module Redd
+  # A container for the client's access to their account via OAuth2
   class OAuth2Access
+    # @!attribute [r] access_token
+    #   @return [String] The access token used to access the users account.
     attr_reader :access_token
 
+    # @!attribute [r] refresh_token
+    #   @return [String, nil] The refresh token, if the access was permanent.
     attr_reader :refresh_token
 
+    # @!attribute [r] scope
+    #   @return [Array] The scope that the client is allowed to access.
     attr_reader :scope
 
+    # @!attribute [r] duration
+    #   @return [Symbol] Time the client is given access (temporary/permanent)
     attr_reader :duration
 
+    # @!attribute [r] expires_at
+    #   @return [Time] The time when the access token expires.
     attr_reader :expires_at
 
+    # @param response [String] The response body containing the required info.
     def initialize(response)
       @access_token = response[:access_token]
       @refresh_token = response[:refresh_token]
@@ -20,21 +32,25 @@ module Redd
       @expires_at =
         if response[:expires_at]
           Time.at(response[:expires_at])
-        else	            
+        else
           Time.now + response[:expires_in]
         end
     end
 
+    # Refresh the object with the new response.
+    # This happens when a new access token is requested using a request token.
+    # @param response [Hash] The new response body.
     def refresh(response)
       @access_token = response[:access_token]
       @expires_at = Time.now + response[:expires_in]
-      self
     end
 
+    # @return [Boolean] Whether the access has expired.
     def expired?
       Time.now > @expires_at
     end
 
+    # @return [String] A JSON representation of the data that can be loaded later.
     def to_json
       MultiJson.dump(
         access_token: @access_token,
@@ -44,9 +60,11 @@ module Redd
       )
     end
 
+    # Create a new instance of the class from the JSON returned from #to_json
+    # @return [OAuth2Access]
     def self.from_json(json)
       hash = MultiJson.load(json, symbolize_keys: true)
       new(hash)
     end
   end
-end
+end

data/lib/redd/object/more_comments.rb

@@ -1,5 +1,6 @@
 module Redd
   module Object
+    # The model for a morecomments object
     class MoreComments < Redd::Base
       attr_reader :count
       attr_reader :parent_id

data/lib/redd/object/private_message.rb

@@ -2,6 +2,7 @@ require "redd/thing"
 
 module Redd
   module Object
+    # The model for private messages
     class PrivateMessage < Redd::Thing
       require "redd/thing/inboxable"
 
@@ -20,7 +21,7 @@ module Redd
       attr_reader :author
 
       alias_method :from, :author
-      alias_method :to, :author
+      alias_method :to, :dest
 
       def created
         @created ||= Time.at(@attributes[:created_utc])

data/lib/redd/object/submission.rb

@@ -60,6 +60,10 @@ module Redd
       alias_method :self?, :is_self
       alias_method :comments_count, :num_comments
 
+      def subreddit_name
+        @subreddit_name ||= @attributes[:subreddit]
+      end
+
       def subreddit
         @subreddit ||= client.subreddit(@attributes[:subreddit])
       end

data/lib/redd/object/user.rb

@@ -2,6 +2,7 @@ require "redd/thing"
 
 module Redd
   module Object
+    # The model for a reddit user
     class User < Redd::Thing
       require "redd/thing/messageable"
 

data/lib/redd/response/raise_error.rb

@@ -8,7 +8,8 @@ module Redd
       # @param faraday
       def call(faraday)
         @app.call(faraday).on_complete do |env|
-          if error = Redd::Error.from_response(env)
+          error = Redd::Error.from_response(env)
+          if error
             if error == Redd::Error::RateLimited
               time = env.body[:json][:ratelimit]
               fail error.new(env, time)

data/lib/redd/thing/editable.rb

@@ -2,6 +2,7 @@ require "redd/thing"
 
 module Redd
   class Thing
+    # A Redd::Object that can be edited
     module Editable
       def delete
         client.delete(self)

data/lib/redd/thing/hideable.rb

@@ -2,6 +2,7 @@ require "redd/thing"
 
 module Redd
   class Thing
+    # A Redd::Object that can be hidden
     module Hideable
       def hide
         client.hide(self)

data/lib/redd/thing/inboxable.rb

@@ -2,6 +2,7 @@ require "redd/thing"
 
 module Redd
   class Thing
+    # A Redd::Object that can be added to one's inbox
     module Inboxable
       def mark_as_read
         client.mark_as_read(self)

data/lib/redd/thing/messageable.rb

@@ -2,16 +2,10 @@ require "redd/thing"
 
 module Redd
   class Thing
+    # A Redd::Object that can be sent a message
     module Messageable
       def send_message(subject, text, captcha = nil, identifier = nil)
-        to = case self
-             when Redd::Object::Subreddit
-               "/r/" + display_name
-             when Redd::Object::User
-               name
-             end
-
-        client.send_message(to, subject, text, captcha, identifier)
+        client.send_message(self, subject, text, captcha, identifier)
       end
     end
   end

data/lib/redd/thing/moderatable.rb

@@ -2,6 +2,7 @@ require "redd/thing"
 
 module Redd
   class Thing
+    # A Redd::Object that can be moderated
     module Moderatable
       def approve
         client.approve(self)

data/lib/redd/thing/reportable.rb

@@ -2,6 +2,7 @@ require "redd/thing"
 
 module Redd
   class Thing
+    # A Redd::Object that can be reported to the mods
     module Reportable
       def report
         client.report(self)

data/lib/redd/thing/saveable.rb

@@ -2,6 +2,7 @@ require "redd/thing"
 
 module Redd
   class Thing
+    # A Redd::Object that can be saved
     module Saveable
       def save(category = nil)
         client.save(self, category)

data/lib/redd/thing/voteable.rb

@@ -2,6 +2,7 @@ require "redd/thing"
 
 module Redd
   class Thing
+    # A Redd::Object that can be voted on
     module Voteable
       def upvote
         client.upvote(self)
@@ -16,7 +17,6 @@ module Redd
       end
 
       alias_method :clear_vote, :unvote
-
     end
   end
 end

data/lib/redd/version.rb

@@ -1,5 +1,5 @@
 # The main Redd module.
 module Redd
   # The semantic version number for Redd.
-  VERSION = "0.4.3"
+  VERSION = "0.5.0"
 end

data/spec/redd/client/unauthenticated_spec.rb

@@ -12,4 +12,4 @@ describe Redd::Client::Unauthenticated, :vcr do
     expect(newclient.user_agent).to eq("SPEC_USERAGENT")
     expect(newclient.api_endpoint).to eq("SPEC_ENDPOINT.COM")
   end
-end
+end

data/spec/redd/rate_limit_spec.rb

@@ -2,19 +2,19 @@ describe Redd::RateLimit do
   let(:rate_limit) { Redd::RateLimit.new }
 
   it "waits two seconds between consecutive requests" do
-    rate_limit.after_limit {  }
+    rate_limit.after_limit {}
     start_time = Time.now
-    rate_limit.after_limit {  }
+    rate_limit.after_limit {}
     end_time = Time.now
 
     expect(end_time - start_time).to be_within(0.1).of(2)
   end
 
   it "doesn't wait if two seconds have passed since last request" do
-    rate_limit.after_limit {  }
+    rate_limit.after_limit {}
     sleep(2)
     start_time = Time.now
-    rate_limit.after_limit {  }
+    rate_limit.after_limit {}
     end_time = Time.now
 
     expect(end_time - start_time).to be_within(0.1).of(0)
@@ -22,7 +22,7 @@ describe Redd::RateLimit do
 
   it "stores the time the last request was made" do
     time = Time.now
-    rate_limit.after_limit {  }
+    rate_limit.after_limit {}
 
     expect(rate_limit.last_request_time).to be_within(0.1).of(time)
   end