Skip to content
Browse files

Flesh out YARD documentation

  • Loading branch information...
1 parent 221cb65 commit 9e032aa1e4058c2c4a455df4aa7e2d6d13cc50b1 @sferik committed Oct 20, 2011
View
11 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
View
4 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
View
15 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
View
3 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)
View
3 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
View
14 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
View
4 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
View
11 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
View
5 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
View
3 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
View
5 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
View
3 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)
View
6 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
View
4 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
View
2 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
View
3 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
View
2 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
View
1 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
View
2 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
View
3 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
View
1 lib/twitter/request/oauth.rb
@@ -20,6 +20,7 @@ def call(env)
def initialize(app, options)
@app, @options = app, options
end
+
end
end
end
View
2 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
View
1 lib/twitter/response/parse_json.rb
@@ -17,6 +17,7 @@ def parse(body)
::MultiJson.decode(body)
end
end
+
end
end
end
View
2 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
View
2 lib/twitter/response/raise_server_error.rb
@@ -6,6 +6,7 @@
module Twitter
module Response
class RaiseServerError < Faraday::Response::Middleware
+
def on_complete(env)
case env[:status].to_i
when 500
@@ -22,6 +23,7 @@ def on_complete(env)
def error_message(env, body=nil)
"#{env[:method].to_s.upcase} #{env[:url].to_s}: #{[env[:status].to_s + ':', body].compact.join(' ')} Check http://status.twitter.com/ for updates on the status of the Twitter service."
end
+
end
end
end
View
2 lib/twitter/saved_search.rb
@@ -6,6 +6,8 @@ class SavedSearch < Twitter::Base
include Twitter::Creatable
lazy_attr_reader :id, :name, :position, :query
+ # @param other [Twiter::SavedSearch]
+ # @return [Boolean]
def ==(other)
super || (other.class == self.class && other.id == self.id)
end
View
3 lib/twitter/search.rb
@@ -22,8 +22,9 @@ class Search < API
attr_reader :query
- # Creates a new search
+ # Initializes a new Search object
#
+ # @return [Twitter::Search]
# @example Initialize a Twitter search
# search = Twitter::Search.new
def initialize(*)
View
1 lib/twitter/settings.rb
@@ -8,6 +8,7 @@ class Settings < Twitter::Base
:time_zone
alias :protected? :protected
+ # @return [Twitter::Place]
def trend_location
@trend_location ||= Twitter::Place.new(@attrs['trend_location'].first) unless @attrs['trend_location'].nil? || @attrs['trend_location'].empty?
end
View
2 lib/twitter/size.rb
@@ -6,6 +6,8 @@ class Size < Twitter::Base
alias :height :h
alias :width :w
+ # @param other [Twiter::Size]
+ # @return [Boolean]
def ==(other)
super || (other.class == self.class && other.h == self.h && other.w == self.w)
end
View
12 lib/twitter/status.rb
@@ -18,53 +18,65 @@ class Status < Twitter::Base
alias :retweeted? :retweeted
alias :truncated? :truncated
+ # @param other [Twiter::Status]
+ # @return [Boolean]
def ==(other)
super || (other.class == self.class && other.id == self.id)
end
+ # @return [Array<String>]
def all_urls
@all_urls ||= begin
all_urls = [ urls, expanded_urls ].flatten.compact.uniq
all_urls.length > 0 ? all_urls : nil
end
end
+ # @return [Array<String>]
def expanded_urls
@expanded_urls ||= Array(@attrs['entities']['urls']).map do |url|
url['expanded_url']
end unless @attrs['entities'].nil?
end
+ # @return [Twitter::Point, Twitter::Polygon]
def geo
@geo ||= Twitter::GeoFactory.new(@attrs['geo']) unless @attrs['geo'].nil?
end
+ # @return [Array<String>]
def hashtags
@hashtags ||= Twitter::Extractor.extract_hashtags(@attrs['text']) unless @attrs['text'].nil?
end
+ # @return [Array]
def media
@media ||= Array(@attrs['entities']['media']).map do |media|
Twitter::MediaFactory.new(media)
end unless @attrs['entities'].nil?
end
+ # @return [Twitter::Metadata]
def metadata
@metadata ||= Twitter::Metadata.new(@attrs['metadata']) unless @attrs['metadata'].nil?
end
+ # @return [Twitter::Place]
def place
@place ||= Twitter::Place.new(@attrs['place']) unless @attrs['place'].nil?
end
+ # @return [Array<String>]
def urls
@urls ||= Twitter::Extractor.extract_urls(@attrs['text']) unless @attrs['text'].nil?
end
+ # @return [Twitter::User]
def user
@user ||= Twitter::User.new(@attrs['user'].merge('status' => self.to_hash.delete_if{|key, value| key == 'user'})) unless @attrs['user'].nil?
end
+ # @return [Array<String>]
def user_mentions
@user_mentions ||= Twitter::Extractor.extract_mentioned_screen_names(@attrs['text']) unless @attrs['text'].nil?
end
View
3 lib/twitter/suggestion.rb
@@ -5,10 +5,13 @@ module Twitter
class Suggestion < Twitter::Base
lazy_attr_reader :name, :size, :slug
+ # @param other [Twiter::Suggestion]
+ # @return [Boolean]
def ==(other)
super || (other.class == self.class && other.slug == self.slug)
end
+ # @return [Array<Twitter::User>]
def users
@users = Array(@attrs['users']).map do |user|
Twitter::User.new(user)
View
2 lib/twitter/trend.rb
@@ -4,6 +4,8 @@ module Twitter
class Trend < Twitter::Base
lazy_attr_reader :events, :name, :promoted_content, :query, :url
+ # @param other [Twiter::Trend]
+ # @return [Boolean]
def ==(other)
super || (other.class == self.class && other.name == self.name)
end
View
3 lib/twitter/user.rb
@@ -49,10 +49,13 @@ class User < Twitter::Base
alias :verified? :verified
alias :want_retweets? :want_retweets
+ # @param other [Twiter::User]
+ # @return [Boolean]
def ==(other)
super || (other.class == self.class && other.id == self.id)
end
+ # @return [Twitter::Status]
def status
@status ||= Twitter::Status.new(@attrs['status'].merge('user' => self.to_hash.delete_if{|key, value| key == 'status'})) unless @attrs['status'].nil?
end
View
5 lib/twitter/version.rb
@@ -1,22 +1,27 @@
module Twitter
class Version
+ # @return [Integer]
def self.major
2
end
+ # @return [Integer]
def self.minor
0
end
+ # @return [Integer]
def self.patch
0
end
+ # @return [String, NilClass]
def self.pre
nil
end
+ # @return [String]
def self.to_s
[major, minor, patch, pre].compact.join('.')
end

0 comments on commit 9e032aa

Please sign in to comment.
Something went wrong with that request. Please try again.