twitter 8.2.0 → 8.3.0

data/lib/twitter/identity.rb

@@ -2,15 +2,25 @@ require "equalizer"
 require "twitter/base"
 
 module Twitter
-  class Identity < Twitter::Base
+  # Base class for Twitter objects with an identity
+  class Identity < Base
     include Equalizer.new(:id)
+
+    # The unique identifier for this object
+    #
+    # @api public
+    # @example
+    #   tweet.id
     # @return [Integer]
     attr_reader :id
 
     # Initializes a new object
     #
-    # @param attrs [Hash]
-    # @raise [ArgumentError] Error raised when supplied argument is missing an :id key.
+    # @api public
+    # @example
+    #   Twitter::Identity.new(id: 123)
+    # @param attrs [Hash] The attributes hash
+    # @raise [ArgumentError] Error raised when argument is missing an :id key
     # @return [Twitter::Identity]
     def initialize(attrs = {})
       attrs.fetch(:id)

data/lib/twitter/language.rb

@@ -1,7 +1,27 @@
 require "twitter/base"
 
 module Twitter
-  class Language < Twitter::Base
+  # Represents a Twitter supported language
+  class Language < Base
+    # The language code
+    #
+    # @api public
+    # @example
+    #   language.code
+    # @return [String]
+
+    # The language name
+    #
+    # @api public
+    # @example
+    #   language.name
+    # @return [String]
+
+    # The language status
+    #
+    # @api public
+    # @example
+    #   language.status
     # @return [String]
     attr_reader :code, :name, :status
   end

data/lib/twitter/list.rb

@@ -2,37 +2,127 @@ require "twitter/creatable"
 require "twitter/identity"
 
 module Twitter
-  class List < Twitter::Identity
-    include Twitter::Creatable
+  # Represents a Twitter list
+  class List < Identity
+    include Creatable
+
+    # The number of members in this list
+    #
+    # @api public
+    # @example
+    #   list.member_count
+    # @return [Integer]
+
+    # The number of subscribers to this list
+    #
+    # @api public
+    # @example
+    #   list.subscriber_count
     # @return [Integer]
     attr_reader :member_count, :subscriber_count
+
+    # The description of this list
+    #
+    # @api public
+    # @example
+    #   list.description
+    # @return [String]
+
+    # The full name of this list
+    #
+    # @api public
+    # @example
+    #   list.full_name
+    # @return [String]
+
+    # The mode of this list (public or private)
+    #
+    # @api public
+    # @example
+    #   list.mode
+    # @return [String]
+
+    # The name of this list
+    #
+    # @api public
+    # @example
+    #   list.name
+    # @return [String]
+
+    # The slug of this list
+    #
+    # @api public
+    # @example
+    #   list.slug
     # @return [String]
     attr_reader :description, :full_name, :mode, :name, :slug
 
     object_attr_reader :User, :user
     predicate_attr_reader :following
 
-    # @return [Addressable::URI] The URI to the list members.
+    # Returns the URI to the list members
+    #
+    # @api public
+    # @example
+    #   list.members_uri
+    # @return [URI::Generic]
     def members_uri
-      Addressable::URI.parse("#{uri}/members") if uri?
+      URI.parse("#{uri}/members") if uri?
     end
     memoize :members_uri
-    alias members_url members_uri
 
-    # @return [Addressable::URI] The URI to the list subscribers.
+    # @!method members_url
+    #   Returns the URL to the list members
+    #   @api public
+    #   @example
+    #     list.members_url
+    #   @return [URI::Generic]
+    alias_method :members_url, :members_uri
+
+    # Returns the URI to the list subscribers
+    #
+    # @api public
+    # @example
+    #   list.subscribers_uri
+    # @return [URI::Generic]
     def subscribers_uri
-      Addressable::URI.parse("#{uri}/subscribers") if uri?
+      URI.parse("#{uri}/subscribers") if uri?
     end
     memoize :subscribers_uri
-    alias subscribers_url subscribers_uri
 
-    # @return [Addressable::URI] The URI to the list.
+    # @!method subscribers_url
+    #   Returns the URL to the list subscribers
+    #   @api public
+    #   @example
+    #     list.subscribers_url
+    #   @return [URI::Generic]
+    alias_method :subscribers_url, :subscribers_uri
+
+    # Returns the URI to the list
+    #
+    # @api public
+    # @example
+    #   list.uri
+    # @return [URI::Generic]
     def uri
-      Addressable::URI.parse("https://twitter.com/#{user.screen_name}/#{slug}") if slug? && user.screen_name?
+      URI.parse("https://twitter.com/#{user.screen_name}/#{slug}") if slug? && user.screen_name?
     end
     memoize :uri
-    alias url uri
 
+    # @!method url
+    #   Returns the URL to the list
+    #   @api public
+    #   @example
+    #     list.url
+    #   @return [URI::Generic]
+    alias_method :url, :uri
+
+    # Returns true if a URI is available for this list
+    #
+    # @api public
+    # @example
+    #   list.uri?
+    # @return [Boolean]
     def uri?
       !!uri
     end

data/lib/twitter/media/animated_gif.rb

@@ -2,6 +2,7 @@ require "twitter/media/video"
 
 module Twitter
   module Media
+    # Represents a Twitter animated GIF media object
     class AnimatedGif < Video
     end
   end

data/lib/twitter/media/photo.rb

@@ -2,24 +2,40 @@ require "memoizable"
 require "twitter/identity"
 
 module Twitter
+  # Namespace for Twitter media types
   module Media
+    # Represents a Twitter photo media object
     class Photo < Twitter::Identity
       include Memoizable
 
+      # The indices of this media in the text
+      #
+      # @api public
+      # @example
+      #   photo.indices
       # @return [Array<Integer>]
       attr_reader :indices
 
+      # The media type
+      #
+      # @api public
+      # @example
+      #   photo.type
       # @return [String]
       attr_reader :type
 
       display_uri_attr_reader
       uri_attr_reader :expanded_uri, :media_uri, :media_uri_https, :uri
 
-      # Returns an array of photo sizes
+      # Returns a hash of photo sizes
       #
-      # @return [Array<Twitter::Size>]
+      # @api public
+      # @example
+      #   photo.sizes
+      # @return [Hash{Symbol => Twitter::Size}]
       def sizes
-        @attrs.fetch(:sizes, []).each_with_object({}) do |(key, value), object|
+        result = {} # : Hash[Symbol, Size]
+        @attrs.fetch(:sizes, []).each_with_object(result) do |(key, value), object|
           object[key] = Size.new(value)
         end
       end

data/lib/twitter/media/video.rb

@@ -4,23 +4,38 @@ require "twitter/media/video_info"
 
 module Twitter
   module Media
+    # Represents a Twitter video media object
     class Video < Twitter::Identity
       include Memoizable
 
+      # The indices of this media in the text
+      #
+      # @api public
+      # @example
+      #   video.indices
       # @return [Array<Integer>]
       attr_reader :indices
 
+      # The media type
+      #
+      # @api public
+      # @example
+      #   video.type
       # @return [String]
       attr_reader :type
 
       display_uri_attr_reader
       uri_attr_reader :expanded_uri, :media_uri, :media_uri_https, :uri
 
-      # Returns an array of photo sizes
+      # Returns a hash of video sizes
       #
-      # @return [Array<Twitter::Size>]
+      # @api public
+      # @example
+      #   video.sizes
+      # @return [Hash{Symbol => Twitter::Size}]
       def sizes
-        @attrs.fetch(:sizes, []).each_with_object({}) do |(key, value), object|
+        result = {} # : Hash[Symbol, Size]
+        @attrs.fetch(:sizes, []).each_with_object(result) do |(key, value), object|
           object[key] = Size.new(value)
         end
       end
@@ -28,6 +43,9 @@ module Twitter
 
       # Returns video info
       #
+      # @api public
+      # @example
+      #   video.video_info
       # @return [Twitter::Media::VideoInfo]
       def video_info
         VideoInfo.new(@attrs[:video_info]) unless @attrs[:video_info].nil?

data/lib/twitter/media/video_info.rb

@@ -3,17 +3,31 @@ require "twitter/variant"
 
 module Twitter
   module Media
+    # Contains video metadata information
     class VideoInfo < Twitter::Base
       include Memoizable
 
-      # @return [Array<Integer]
+      # The aspect ratio of the video
+      #
+      # @api public
+      # @example
+      #   video_info.aspect_ratio
+      # @return [Array<Integer>]
       attr_reader :aspect_ratio
 
+      # The duration of the video in milliseconds
+      #
+      # @api public
+      # @example
+      #   video_info.duration_millis
       # @return [Integer]
       attr_reader :duration_millis
 
       # Returns an array of video variants
       #
+      # @api public
+      # @example
+      #   video_info.variants
       # @return [Array<Twitter::Variant>]
       def variants
         @attrs.fetch(:variants, []).collect do |variant|

data/lib/twitter/media_factory.rb

@@ -4,12 +4,16 @@ require "twitter/media/photo"
 require "twitter/media/video"
 
 module Twitter
+  # Factory for creating media objects based on type
   class MediaFactory < Twitter::Factory
     class << self
-      # Construct a new media object
+      # Constructs a new media object
       #
-      # @param attrs [Hash]
-      # @raise [IndexError] Error raised when supplied argument is missing a :type key.
+      # @api public
+      # @example
+      #   Twitter::MediaFactory.new(type: "photo", id: 123)
+      # @param attrs [Hash] The attributes hash with a :type key
+      # @raise [IndexError] Error raised when argument is missing a :type key
       # @return [Twitter::Media]
       def new(attrs = {})
         super(:type, Media, attrs)

data/lib/twitter/metadata.rb

@@ -1,7 +1,20 @@
 require "twitter/base"
 
 module Twitter
-  class Metadata < Twitter::Base
+  # Represents metadata about a search result
+  class Metadata < Base
+    # The ISO language code
+    #
+    # @api public
+    # @example
+    #   metadata.iso_language_code
+    # @return [String]
+
+    # The result type
+    #
+    # @api public
+    # @example
+    #   metadata.result_type
     # @return [String]
     attr_reader :iso_language_code, :result_type
   end

data/lib/twitter/null_object.rb

@@ -1,7 +1,9 @@
 require "naught"
 
 module Twitter
-  NullObject = Naught.build do |config| # rubocop:disable Metrics/BlockLength
+  # A null object that absorbs all method calls and returns itself
+  # @see https://github.com/avdi/naught
+  NullObject = Naught.build do |config| # steep:ignore # rubocop:disable Metrics/BlockLength
     include Comparable
 
     config.black_hole
@@ -9,18 +11,18 @@ module Twitter
     config.define_implicit_conversions
     config.predicates_return false
 
-    def !
+    def ! # steep:ignore UndeclaredMethodDefinition
       true
     end
 
-    def respond_to?(*)
+    def respond_to?(*_args) # steep:ignore DifferentMethodParameterKind
       true
     end
 
     def instance_of?(klass)
-      raise(TypeError, "class or module required") unless klass.is_a?(Class)
-
-      self.class == klass
+      Object.instance_method(:instance_of?).bind_call(self, klass)
+    rescue TypeError
+      false
     end
 
     def kind_of?(mod)
@@ -31,7 +33,7 @@ module Twitter
 
     alias_method :is_a?, :kind_of?
 
-    def <=>(other)
+    def <=>(other) # steep:ignore MethodBodyTypeMismatch
       if other.is_a?(self.class)
         0
       else
@@ -39,27 +41,27 @@ module Twitter
       end
     end
 
-    def nil?
+    def nil? # steep:ignore MethodBodyTypeMismatch
       true
     end
 
-    def as_json(*)
+    def as_json(*) # steep:ignore UndeclaredMethodDefinition,FallbackAny
       "null"
     end
 
-    def to_json(*args)
-      nil.to_json(*args)
+    def to_json(*) # steep:ignore UndeclaredMethodDefinition,FallbackAny
+      nil.to_json(*) # steep:ignore NoMethod
     end
 
-    def presence
+    def presence # steep:ignore UndeclaredMethodDefinition
       nil
     end
 
-    def blank?
+    def blank? # steep:ignore UndeclaredMethodDefinition
       true
     end
 
-    def present?
+    def present? # steep:ignore UndeclaredMethodDefinition
       false
     end
   end

data/lib/twitter/oembed.rb

@@ -1,12 +1,66 @@
 require "twitter/base"
 
 module Twitter
-  class OEmbed < Twitter::Base
+  # Represents oEmbed data for a Tweet
+  class OEmbed < Base
+    # The height of the embedded content
+    #
+    # @api public
+    # @example
+    #   oembed.height
+    # @return [Integer]
+
+    # The width of the embedded content
+    #
+    # @api public
+    # @example
+    #   oembed.width
     # @return [Integer]
     attr_reader :height, :width
+
+    # The author name
+    #
+    # @api public
+    # @example
+    #   oembed.author_name
+    # @return [String]
+
+    # The cache age in seconds
+    #
+    # @api public
+    # @example
+    #   oembed.cache_age
+    # @return [String]
+
+    # The HTML to embed the Tweet
+    #
+    # @api public
+    # @example
+    #   oembed.html
+    # @return [String]
+
+    # The provider name
+    #
+    # @api public
+    # @example
+    #   oembed.provider_name
+    # @return [String]
+
+    # The oEmbed type
+    #
+    # @api public
+    # @example
+    #   oembed.type
+    # @return [String]
+
+    # The oEmbed version
+    #
+    # @api public
+    # @example
+    #   oembed.version
     # @return [String]
     attr_reader :author_name, :cache_age, :html, :provider_name, :type,
-                :version
+      :version
 
     uri_attr_reader :author_uri, :provider_uri, :uri
   end

data/lib/twitter/place.rb

@@ -2,42 +2,110 @@ require "memoizable"
 require "twitter/identity"
 
 module Twitter
-  class Place < Twitter::Identity
+  # Represents a Twitter place
+  class Place < Identity
     include Memoizable
 
+    # The place attributes hash
+    #
+    # @api public
+    # @example
+    #   place.attributes
     # @return [Hash]
     attr_reader :attributes
+
+    # The country name
+    #
+    # @api public
+    # @example
+    #   place.country
+    # @return [String]
+
+    # The full name of the place
+    #
+    # @api public
+    # @example
+    #   place.full_name
+    # @return [String]
+
+    # The place name
+    #
+    # @api public
+    # @example
+    #   place.name
     # @return [String]
     attr_reader :country, :full_name, :name
-    alias woe_id id
-    alias woeid id
+
+    # The Where On Earth ID
+    #
+    # @!method woe_id
+    # @api public
+    # @example
+    #   place.woe_id
+    # @return [Integer]
+    alias_method :woe_id, :id
+
+    # The Where On Earth ID
+    #
+    # @!method woeid
+    # @api public
+    # @example
+    #   place.woeid
+    # @return [Integer]
+    alias_method :woeid, :id
     object_attr_reader :GeoFactory, :bounding_box
     object_attr_reader :Place, :contained_within
-    alias contained? contained_within?
+
+    # Returns true if this place is contained within another
+    #
+    # @!method contained?
+    # @api public
+    # @example
+    #   place.contained?
+    # @return [Boolean]
+    alias_method :contained?, :contained_within?
     uri_attr_reader :uri
 
     # Initializes a new place
     #
-    # @param attrs [Hash]
-    # @raise [ArgumentError] Error raised when supplied argument is missing a :woeid key.
+    # @api public
+    # @example
+    #   Twitter::Place.new(woeid: 12345)
+    # @param attrs [Hash] The attributes hash
+    # @raise [ArgumentError] Error raised when argument is missing a :woeid key
     # @return [Twitter::Place]
     def initialize(attrs = {})
       attrs[:id] ||= attrs.fetch(:woeid)
       super
     end
 
+    # Returns the country code
+    #
+    # @api public
+    # @example
+    #   place.country_code
     # @return [String]
     def country_code
       @attrs[:country_code] || @attrs[:countryCode]
     end
     memoize :country_code
 
+    # Returns the parent place ID
+    #
+    # @api public
+    # @example
+    #   place.parent_id
     # @return [Integer]
     def parent_id
       @attrs[:parentid]
     end
     memoize :parent_id
 
+    # Returns the place type
+    #
+    # @api public
+    # @example
+    #   place.place_type
     # @return [String]
     def place_type
       @attrs[:place_type] || (@attrs[:placeType] && @attrs[:placeType][:name])