twitter 8.2.0 → 8.3.1

data/lib/twitter/trend_results.rb

@@ -5,19 +5,43 @@ require "twitter/null_object"
 require "twitter/utils"
 
 module Twitter
+  # Represents a collection of trending topics
   class TrendResults
-    include Twitter::Creatable
-    include Twitter::Enumerable
-    include Twitter::Utils
+    include Creatable
+    include Enumerable
+    include Utils
     include Memoizable
+
+    # The raw attributes hash
+    #
+    # @api public
+    # @example
+    #   results.attrs
     # @return [Hash]
     attr_reader :attrs
-    alias to_h attrs
-    alias to_hash to_h
+
+    # @!method to_h
+    #   Returns the attributes as a hash
+    #   @api public
+    #   @example
+    #     results.to_h
+    #   @return [Hash]
+    alias_method :to_h, :attrs
+
+    # @!method to_hash
+    #   Returns the attributes as a hash
+    #   @api public
+    #   @example
+    #     results.to_hash
+    #   @return [Hash]
+    alias_method :to_hash, :to_h
 
     # Initializes a new TrendResults object
     #
-    # @param attrs [Hash]
+    # @api public
+    # @example
+    #   Twitter::TrendResults.new(trends: [])
+    # @param attrs [Hash] The attributes hash
     # @return [Twitter::TrendResults]
     def initialize(attrs = {})
       @attrs = attrs
@@ -26,25 +50,44 @@ module Twitter
       end
     end
 
-    # Time when the object was created on Twitter
+    # Returns the time when trends were retrieved
     #
+    # @api public
+    # @example
+    #   results.as_of
     # @return [Time]
     def as_of
       Time.parse(@attrs[:as_of]).utc unless @attrs[:as_of].nil?
     end
     memoize :as_of
 
+    # Returns true if as_of is available
+    #
+    # @api public
+    # @example
+    #   results.as_of?
+    # @return [Boolean]
     def as_of?
       !!@attrs[:as_of]
     end
     memoize :as_of?
 
+    # Returns the location for these trends
+    #
+    # @api public
+    # @example
+    #   results.location
     # @return [Twitter::Place, NullObject]
     def location
       location? ? Place.new(@attrs[:locations].first) : NullObject.new
     end
     memoize :location
 
+    # Returns true if location is available
+    #
+    # @api public
+    # @example
+    #   results.location?
     # @return [Boolean]
     def location?
       !@attrs[:locations].nil? && !@attrs[:locations].first.nil?

data/lib/twitter/tweet.rb

@@ -3,42 +3,189 @@ require "twitter/entities"
 require "twitter/identity"
 
 module Twitter
-  class Tweet < Twitter::Identity
-    include Twitter::Creatable
-    include Twitter::Entities
+  # Represents a Twitter tweet
+  class Tweet < Identity
+    include Creatable
+    include Entities
+
+    # The filter level of the tweet
+    #
+    # @api public
+    # @example
+    #   tweet.filter_level
+    # @return [String]
+
+    # The screen name of the user being replied to
+    #
+    # @api public
+    # @example
+    #   tweet.in_reply_to_screen_name
+    # @return [String]
+
+    # The language of the tweet
+    #
+    # @api public
+    # @example
+    #   tweet.lang
+    # @return [String]
+
+    # The source of the tweet
+    #
+    # @api public
+    # @example
+    #   tweet.source
+    # @return [String]
+
+    # The text of the tweet
+    #
+    # @api public
+    # @example
+    #   tweet.text
     # @return [String]
     attr_reader :filter_level, :in_reply_to_screen_name, :lang, :source, :text
+
+    # The number of times this tweet has been favorited
+    #
+    # @api public
+    # @example
+    #   tweet.favorite_count
+    # @return [Integer]
+
+    # The ID of the status being replied to
+    #
+    # @api public
+    # @example
+    #   tweet.in_reply_to_status_id
+    # @return [Integer]
+
+    # The ID of the user being replied to
+    #
+    # @api public
+    # @example
+    #   tweet.in_reply_to_user_id
+    # @return [Integer]
+
+    # The number of times this tweet has been quoted
+    #
+    # @api public
+    # @example
+    #   tweet.quote_count
+    # @return [Integer]
+
+    # The number of replies to this tweet
+    #
+    # @api public
+    # @example
+    #   tweet.reply_count
+    # @return [Integer]
+
+    # The number of times this tweet has been retweeted
+    #
+    # @api public
+    # @example
+    #   tweet.retweet_count
     # @return [Integer]
     attr_reader :favorite_count, :in_reply_to_status_id, :in_reply_to_user_id,
-                :quote_count, :reply_count, :retweet_count
-    alias in_reply_to_tweet_id in_reply_to_status_id
-    alias reply? in_reply_to_user_id?
+      :quote_count, :reply_count, :retweet_count
+
+    # @!method in_reply_to_tweet_id
+    #   The ID of the tweet being replied to
+    #   @api public
+    #   @example
+    #     tweet.in_reply_to_tweet_id
+    #   @return [Integer]
+    alias_method :in_reply_to_tweet_id, :in_reply_to_status_id
+
+    # Returns true if this is a reply
+    #
+    # @!method reply?
+    # @api public
+    # @example
+    #   tweet.reply?
+    # @return [Boolean]
+    alias_method :reply?, :in_reply_to_user_id?
     object_attr_reader :GeoFactory, :geo
     object_attr_reader :Metadata, :metadata
     object_attr_reader :Place, :place
     object_attr_reader :Tweet, :retweeted_status
     object_attr_reader :Tweet, :quoted_status
     object_attr_reader :Tweet, :current_user_retweet
-    alias retweeted_tweet retweeted_status
-    alias retweet? retweeted_status?
-    alias retweeted_tweet? retweeted_status?
-    alias quoted_tweet quoted_status
-    alias quote? quoted_status?
-    alias quoted_tweet? quoted_status?
+
+    # Returns the retweeted tweet
+    #
+    # @!method retweeted_tweet
+    # @api public
+    # @example
+    #   tweet.retweeted_tweet
+    # @return [Twitter::Tweet]
+    alias_method :retweeted_tweet, :retweeted_status
+
+    # Returns true if this is a retweet
+    #
+    # @!method retweet?
+    # @api public
+    # @example
+    #   tweet.retweet?
+    # @return [Boolean]
+    alias_method :retweet?, :retweeted_status?
+
+    # Returns true if this has a retweeted tweet
+    #
+    # @!method retweeted_tweet?
+    # @api public
+    # @example
+    #   tweet.retweeted_tweet?
+    # @return [Boolean]
+    alias_method :retweeted_tweet?, :retweeted_status?
+
+    # Returns the quoted tweet
+    #
+    # @!method quoted_tweet
+    # @api public
+    # @example
+    #   tweet.quoted_tweet
+    # @return [Twitter::Tweet]
+    alias_method :quoted_tweet, :quoted_status
+
+    # Returns true if this is a quote tweet
+    #
+    # @!method quote?
+    # @api public
+    # @example
+    #   tweet.quote?
+    # @return [Boolean]
+    alias_method :quote?, :quoted_status?
+
+    # Returns true if this has a quoted tweet
+    #
+    # @!method quoted_tweet?
+    # @api public
+    # @example
+    #   tweet.quoted_tweet?
+    # @return [Boolean]
+    alias_method :quoted_tweet?, :quoted_status?
     object_attr_reader :User, :user, :status
     predicate_attr_reader :favorited, :possibly_sensitive, :retweeted,
-                          :truncated
+      :truncated
 
-    # Initializes a new object
+    # Initializes a new Tweet object
     #
-    # @param attrs [Hash]
+    # @api public
+    # @example
+    #   Twitter::Tweet.new(id: 123, text: "Hello")
+    # @param attrs [Hash] The attributes hash containing at least :id
     # @return [Twitter::Tweet]
-    def initialize(attrs = {})
-      attrs[:text] = attrs[:full_text] if attrs[:text].nil? && !attrs[:full_text].nil?
+    def initialize(attrs)
+      attrs[:text] ||= attrs[:full_text]
       super
     end
 
-    # @note May be > 280 characters.
+    # Returns the full text of the tweet
+    #
+    # @api public
+    # @note May be > 280 characters
+    # @example
+    #   tweet.full_text
     # @return [String]
     def full_text
       if retweet?
@@ -50,11 +197,23 @@ module Twitter
     end
     memoize :full_text
 
-    # @return [Addressable::URI] The URL to the tweet.
+    # Returns the URI to the tweet
+    #
+    # @api public
+    # @example
+    #   tweet.uri
+    # @return [URI::Generic]
     def uri
-      Addressable::URI.parse("https://twitter.com/#{user.screen_name}/status/#{id}") if user?
+      URI.parse("https://twitter.com/#{user.screen_name}/status/#{id}") if user?
     end
     memoize :uri
-    alias url uri
+
+    # @!method url
+    #   Returns the URL to the tweet
+    #   @api public
+    #   @example
+    #     tweet.url
+    #   @return [URI::Generic]
+    alias_method :url, :uri
   end
 end