Flesh out YARD documentation

lib/twitter/api.rb

@@ -11,11 +11,14 @@ class API
 
     attr_accessor *Config::VALID_OPTIONS_KEYS
 
-    # Creates a new API
-    def initialize(options={})
-      options = Twitter.options.merge(options)
+    # Initializes a new API object
+    #
+    # @param attrs [Hash]
+    # @return [Twitter::API]
+    def initialize(attrs={})
+      attrs = Twitter.options.merge(attrs)
       Config::VALID_OPTIONS_KEYS.each do |key|
-        send("#{key}=", options[key])
+        instance_variable_set("@#{key}".to_sym, attrs[key])
       end
     end
 

lib/twitter/authenticatable.rb

@@ -13,10 +13,10 @@ def credentials
       }
     end
 
-    # Check whether user is authenticated
+    # Check whether credentials are present
     #
     # @return [Boolean]
-    def authenticated?
+    def credentials?
       credentials.values.all?
     end
 

lib/twitter/base.rb

@@ -3,6 +3,12 @@ class Base
     attr_accessor :attrs
     alias :to_hash :attrs
 
+    # Define methods that retrieve the value from an initialized instance variable Hash, using the attribute as a key
+    #
+    # @overload self.lazy_attr_reader(attr)
+    #   @param attr [Symbol]
+    # @overload self.lazy_attr_reader(attrs)
+    #   @param attrs [Array<Symbol>]
     def self.lazy_attr_reader(*attrs)
       attrs.each do |attribute|
         class_eval do
@@ -13,10 +19,17 @@ def self.lazy_attr_reader(*attrs)
       end
     end
 
-    def initialize(attrs = {})
+    # Initializes a new Base object
+    #
+    # @param attrs [Hash]
+    # @return [Twitter::Base]
+    def initialize(attrs={})
       @attrs = attrs.dup
     end
 
+    # Initializes a new Base object
+    #
+    # @param method [String, Symbol] Message to send to the object
     def [](method)
       self.__send__(method.to_sym)
     end

lib/twitter/configuration.rb

@@ -7,6 +7,9 @@ class Configuration < Twitter::Base
     lazy_attr_reader :characters_reserved_per_media, :max_media_per_upload,
       :non_username_paths, :photo_size_limit, :short_url_length, :short_url_length_https
 
+    # Returns an array of photo sizes
+    #
+    # @return [Array<Twitter::Size>]
     def photo_sizes
       @photo_sizes ||= Array(@attrs['photo_sizes']).each_with_object({}) do |(key, value), object|
         object[key] = Twitter::Size.new(value)

lib/twitter/creatable.rb

@@ -3,6 +3,9 @@
 module Twitter
   module Creatable
 
+    # Time when the object was created on Twitter
+    #
+    # @return [Time]
     def created_at
       @created_at ||= Time.parse(@attrs['created_at']) unless @attrs['created_at'].nil?
     end

lib/twitter/cursor.rb

@@ -8,9 +8,15 @@ class Cursor < Twitter::Base
     alias :next :next_cursor
     alias :previous :previous_cursor
 
-    def initialize(attributes, method, klass=nil)
-      super(attributes)
-      @collection = Array(attributes[method.to_s]).map do |item|
+    # Initializes a new Cursor object
+    #
+    # @param attrs [Hash]
+    # @params method [String, Symbol] The name of the method to return the collection
+    # @params klass [Class] The class to instantiate object in the collection
+    # @return [Twitter::Cursor]
+    def initialize(attrs, method, klass=nil)
+      super(attrs)
+      @collection = Array(attrs[method.to_s]).map do |item|
         if klass
           klass.new(item)
         else
@@ -22,11 +28,13 @@ def initialize(attributes, method, klass=nil)
       end
     end
 
+    # @return [Boolean]
     def first?
       previous_cursor.zero?
     end
     alias :first :first?
 
+    # @return [Boolean]
     def last?
       next_cursor.zero?
     end

lib/twitter/direct_message.rb

@@ -7,14 +7,18 @@ class DirectMessage < Twitter::Base
     include Twitter::Creatable
     lazy_attr_reader :id, :text
 
+    # @param other [Twiter::DirectMessage]
+    # @return [Boolean]
     def ==(other)
       super || (other.class == self.class && other.id == self.id)
     end
 
+    # @return [Twitter::User]
     def recipient
       @recipient ||= Twitter::User.new(@attrs['recipient']) unless @attrs['recipient'].nil?
     end
 
+    # @return [Twitter::User]
     def sender
       @sender ||= Twitter::User.new(@attrs['sender']) unless @attrs['sender'].nil?
     end

lib/twitter/error.rb

@@ -3,23 +3,32 @@ module Twitter
   class Error < StandardError
     attr_reader :http_headers
 
+    # Initializes a new Error object
+    #
+    # @param message [String]
+    # @param http_headers [Hash]
+    # @return [Twitter::Error]
     def initialize(message, http_headers)
       @http_headers = Hash[http_headers]
-      super message
+      super(message)
     end
 
+    # @return [Time]
     def ratelimit_reset
       Time.at(@http_headers.values_at('x-ratelimit-reset', 'X-RateLimit-Reset').detect{|value| value}.to_i)
     end
 
+    # @return [Integer]
     def ratelimit_limit
       @http_headers.values_at('x-ratelimit-limit', 'X-RateLimit-Limit').detect{|value| value}.to_i
     end
 
+    # @return [Integer]
     def ratelimit_remaining
       @http_headers.values_at('x-ratelimit-remaining', 'X-RateLimit-Remaining').detect{|value| value}.to_i
     end
 
+    # @return [Integer]
     def retry_after
       [(ratelimit_reset - Time.now).ceil, 0].max
     end

lib/twitter/geo_factory.rb

@@ -4,6 +4,11 @@
 module Twitter
   class GeoFactory
 
+    # Instantiates a new geo object
+    #
+    # @param attrs [Hash]
+    # @raise [ArgumentError] Error raised when supplied argument is missing a type key.
+    # @return [Twitter::Point, Twitter::Polygon]
     def self.new(geo={})
       type = geo['type']
       if type

lib/twitter/list.rb

@@ -7,10 +7,13 @@ class List < Twitter::Base
       :mode, :name, :slug, :subscriber_count, :uri
     alias :following? :following
 
+    # @param other [Twiter::List]
+    # @return [Boolean]
     def ==(other)
       super || (other.class == self.class && other.id == self.id)
     end
 
+    # @return [Twitter::User]
     def user
       @user ||= Twitter::User.new(@attrs['user']) unless @attrs['user'].nil?
     end

lib/twitter/media_factory.rb

@@ -3,6 +3,11 @@
 module Twitter
   class MediaFactory
 
+    # Instantiates a new media object
+    #
+    # @param attrs [Hash]
+    # @raise [ArgumentError] Error raised when supplied argument is missing a type key.
+    # @return [Twitter::Photo]
     def self.new(media={})
       type = media['type']
       if type

lib/twitter/photo.rb

@@ -7,10 +7,13 @@ class Photo < Twitter::Base
     lazy_attr_reader :display_url, :expanded_url, :id, :indices, :media_url,
       :media_url_https, :url
 
+    # @param other [Twiter::Photo]
+    # @return [Boolean]
     def ==(other)
       super || (other.class == self.class && other.id == self.id)
     end
 
+    # @return [Array<Twitter::Size>]
     def sizes
       @sizes ||= Array(@attrs['sizes']).each_with_object({}) do |(key, value), object|
         object[key] = Twitter::Size.new(value)

lib/twitter/place.rb

@@ -6,22 +6,28 @@ class Place < Twitter::Base
     lazy_attr_reader :attributes, :country, :full_name, :id, :name, :url,
       :woeid
 
+    # @param other [Twiter::Place]
+    # @return [Boolean]
     def ==(other)
       super || (other.class == self.class && other.id == self.id)
     end
 
+    # @return [Twitter::Point, Twitter::Polygon]
     def bounding_box
       @bounding_box ||= Twitter::GeoFactory.new(@attrs['bounding_box']) unless @attrs['bounding_box'].nil?
     end
 
+    # @return [String]
     def country_code
       @country_code ||= @attrs['country_code'] || @attrs['countryCode']
     end
 
+    # @return [Integer]
     def parent_id
       @parent_id ||= @attrs['parentid']
     end
 
+    # @return [String]
     def place_type
       @place_type ||= @attrs['place_type'] || @attrs['placeType'] && @attrs['placeType']['name']
     end

lib/twitter/point.rb

@@ -4,15 +4,19 @@ module Twitter
   class Point < Twitter::Base
     lazy_attr_reader :coordinates
 
+    # @param other [Twiter::Point]
+    # @return [Boolean]
     def ==(other)
       super || (other.class == self.class && other.coordinates == self.coordinates)
     end
 
+    # @return [Integer]
     def latitude
       coordinates[0]
     end
     alias :lat :latitude
 
+    # @return [Integer]
     def longitude
       coordinates[1]
     end

lib/twitter/polygon.rb

@@ -4,6 +4,8 @@ module Twitter
   class Polygon < Twitter::Base
     lazy_attr_reader :coordinates
 
+    # @param other [Twiter::Polygon]
+    # @return [Boolean]
     def ==(other)
       super || (other.class == self.class && other.coordinates == self.coordinates)
     end

lib/twitter/rate_limit_status.rb

@@ -4,6 +4,9 @@ module Twitter
   class RateLimitStatus < Twitter::Base
     lazy_attr_reader :hourly_limit, :remaining_hits, :reset_time_in_seconds
 
+    # Time when the authenticating user's rate limit will be reset
+    #
+    # @return [Time]
     def reset_time
       @reset_time ||= Time.parse(@attrs['reset_time']) unless @attrs['reset_time'].nil?
     end

lib/twitter/relationship.rb

@@ -4,10 +4,12 @@
 module Twitter
   class Relationship < Twitter::Base
 
+    # @return [Twitter::User]
     def source
       @source ||= Twitter::User.new(@attrs['source']) unless @attrs['source'].nil?
     end
 
+    # @return [Twitter::User]
     def target
       @target ||= Twitter::User.new(@attrs['target']) unless @attrs['target'].nil?
     end

lib/twitter/request.rb

@@ -11,6 +11,7 @@ def get(path, params={}, options={})
       request(:get, path, params, options)
     end
 
+    # Perform an HTTP POST request
     def post(path, params={}, options={})
       request(:post, path, params, options)
     end

lib/twitter/request/gateway.rb

@@ -3,6 +3,7 @@
 module Twitter
   module Request
     class Gateway < Faraday::Middleware
+
       def call(env)
         url = env[:url].dup
         url.host = @gateway
@@ -13,6 +14,7 @@ def call(env)
       def initialize(app, gateway)
         @app, @gateway = app, gateway
       end
+
     end
   end
 end

lib/twitter/request/multipart_with_file.rb

@@ -3,6 +3,7 @@
 module Twitter
   module Request
     class MultipartWithFile < Faraday::Middleware
+
       def call(env)
         if env[:body].is_a?(Hash)
           env[:body].each do |key, value|
@@ -13,7 +14,6 @@ def call(env)
             end
           end
         end
-
         @app.call(env)
       end
 
@@ -31,6 +31,7 @@ def mime_type(path)
           'application/octet-stream'
         end
       end
+
     end
   end
 end

lib/twitter/request/oauth.rb

@@ -20,6 +20,7 @@ def call(env)
       def initialize(app, options)
         @app, @options = app, options
       end
+
     end
   end
 end

lib/twitter/request/phoenix.rb

@@ -3,6 +3,7 @@
 module Twitter
   module Request
     class Phoenix < Faraday::Middleware
+
       def call(env)
         # Not sure what what the X-Phx (Phoenix?) header is for but it's
         # required to access certain undocumented resources
@@ -15,6 +16,7 @@ def call(env)
       def initialize(app)
         @app = app
       end
+
     end
   end
 end

lib/twitter/response/parse_json.rb

@@ -17,6 +17,7 @@ def parse(body)
           ::MultiJson.decode(body)
         end
       end
+
     end
   end
 end

lib/twitter/response/raise_client_error.rb

@@ -9,6 +9,7 @@
 module Twitter
   module Response
     class RaiseClientError < Faraday::Response::Middleware
+
       def on_complete(env)
         case env[:status].to_i
         when 400
@@ -46,6 +47,7 @@ def error_body(body)
           end
         end
       end
+
     end
   end
 end