twitter 8.1.0 → 8.3.0

data/lib/twitter/rest/search.rb

@@ -3,35 +3,39 @@ require "twitter/search_results"
 
 module Twitter
   module REST
+    # Methods for searching tweets
     module Search
+      # Maximum tweets per request
       MAX_TWEETS_PER_REQUEST = 100
 
-      # Returns tweets that match a specified query.
+      # Returns tweets that match a specified query
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/search/tweets
-      # @see https://dev.twitter.com/rest/public/search
-      # @note Please note that Twitter's search service and, by extension, the Search API is not meant to be an exhaustive source of Tweets. Not all Tweets will be indexed or made available via the search interface.
+      # @note Not all Tweets will be indexed or made available via the search interface.
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.search('twitter')
       # @param query [String] A search term.
       # @param options [Hash] A customizable set of options.
-      # @option options [String] :geocode Returns tweets by users located within a given radius of the given latitude/longitude. The location is preferentially taking from the Geotagging API, but will fall back to their Twitter profile. The parameter value is specified by "latitude,longitude,radius", where radius units must be specified as either "mi" (miles) or "km" (kilometers). Note that you cannot use the near operator via the API to geocode arbitrary locations; however you can use this geocode parameter to search near geocodes directly.
-      # @option options [String] :lang Restricts tweets to the given language, given by an ISO 639-1 code.
-      # @option options [String] :locale Specify the language of the query you are sending (only ja is currently effective). This is intended for language-specific clients and the default should work in the majority of cases.
-      # @option options [String] :result_type Specifies what type of search results you would prefer to receive. Options are "mixed", "recent", and "popular". The current default is "mixed."
-      # @option options [Integer] :count The number of tweets to return per page, up to a maximum of 100.
-      # @option options [String] :until Optional. Returns tweets generated before the given date. Date should be formatted as YYYY-MM-DD.
-      # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.
-      # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
-      # @option options [Boolean] :include_entities The entities node will be disincluded when set to false.
-      # @option options [String] :tweet_mode The entities node will truncate or not tweet text. Options are "compat" and "extended". The current default is "compat" (truncate).
-      # @return [Twitter::SearchResults] Return tweets that match a specified query with search metadata
+      # @option options [String] :geocode Returns tweets by users located within a given radius.
+      # @option options [String] :lang Restricts tweets to the given language.
+      # @option options [String] :locale Specify the language of the query you are sending.
+      # @option options [String] :result_type Specifies result type: mixed, recent, or popular.
+      # @option options [Integer] :count The number of tweets to return per page.
+      # @option options [String] :until Returns tweets generated before the given date.
+      # @option options [Integer] :since_id Returns results with an ID greater than the specified ID.
+      # @option options [Integer] :max_id Returns results with an ID less than the specified ID.
+      # @option options [Boolean] :include_entities Include entities node.
+      # @option options [String] :tweet_mode Tweet text mode: compat or extended.
+      # @return [Twitter::SearchResults] Tweets matching the query with search metadata.
       def search(query, options = {})
         options = options.dup
         options[:count] ||= MAX_TWEETS_PER_REQUEST
-        request = Twitter::REST::Request.new(self, :get, "/1.1/search/tweets.json", options.merge(q: query))
-        Twitter::SearchResults.new(request)
+        request = Request.new(self, :get, "/1.1/search/tweets.json", options.merge(q: query))
+        SearchResults.new(request)
       end
     end
   end

data/lib/twitter/rest/spam_reporting.rb

@@ -3,15 +3,19 @@ require "twitter/user"
 
 module Twitter
   module REST
+    # Methods for reporting spam accounts
     module SpamReporting
       include Twitter::REST::Utils
 
-      # The users specified are blocked by the authenticated user and reported as spammers
+      # Blocks users and reports them as spammers
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/post/users/report_spam
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.report_spam('spammer')
       # @return [Array<Twitter::User>] The reported users.
       # @overload report_spam(*users)
       #   @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen names, or objects.

data/lib/twitter/rest/suggested_users.rb

@@ -5,13 +5,19 @@ require "twitter/user"
 
 module Twitter
   module REST
+    # Methods for accessing suggested users
     module SuggestedUsers
       include Twitter::REST::Utils
 
+      # Returns suggested user categories or users in a category
+      #
+      # @api public
       # @return [Array<Twitter::Suggestion>]
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.suggestions
       # @overload suggestions(options = {})
       #   Returns the list of suggested user categories
       #
@@ -24,24 +30,27 @@ module Twitter
       #   @param slug [String] The short name of list or a category.
       #   @param options [Hash] A customizable set of options.
       def suggestions(*args)
-        arguments = Twitter::Arguments.new(args)
+        arguments = Arguments.new(args)
         if arguments.last
-          perform_get_with_object("/1.1/users/suggestions/#{arguments.pop}.json", arguments.options, Twitter::Suggestion)
+          perform_get_with_object("/1.1/users/suggestions/#{arguments.pop}.json", arguments.options, Suggestion)
         else
-          perform_get_with_objects("/1.1/users/suggestions.json", arguments.options, Twitter::Suggestion)
+          perform_get_with_objects("/1.1/users/suggestions.json", arguments.options, Suggestion)
         end
       end
 
-      # Access the users in a given category of the Twitter suggested user list and return their most recent Tweet if they are not a protected user
+      # Returns users in a given category with their most recent Tweet
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/users/suggestions/:slug/members
       # @rate_limited Yes
       # @authentication Requires user context
+      # @example
+      #   client.suggest_users('technology')
       # @param slug [String] The short name of list or a category.
       # @param options [Hash] A customizable set of options.
       # @return [Array<Twitter::User>]
       def suggest_users(slug, options = {})
-        perform_get_with_objects("/1.1/users/suggestions/#{slug}/members.json", options, Twitter::User)
+        perform_get_with_objects("/1.1/users/suggestions/#{slug}/members.json", options, User)
       end
     end
   end

data/lib/twitter/rest/timelines.rb

@@ -4,36 +4,49 @@ require "twitter/user"
 
 module Twitter
   module REST
+    # Methods for accessing timelines
     module Timelines
       include Twitter::REST::Utils
+
+      # Default number of tweets per request
       DEFAULT_TWEETS_PER_REQUEST = 20
+      # Maximum tweets per request
       MAX_TWEETS_PER_REQUEST = 200
 
-      # Returns the 20 most recent mentions (statuses containing @username) for the authenticating user
+      # Returns the 20 most recent mentions for the authenticating user
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/statuses/mentions_timeline
       # @note This method can only return up to 800 Tweets.
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.mentions_timeline
       # @return [Array<Twitter::Tweet>]
       # @param options [Hash] A customizable set of options.
-      # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
-      # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
-      # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200.
-      # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1.
+      # @option options [Integer] :since_id Returns results with an ID greater than the specified ID.
+      # @option options [Integer] :max_id Returns results with an ID less than the specified ID.
+      # @option options [Integer] :count Specifies the number of records to retrieve.
+      # @option options [Boolean, String, Integer] :trim_user Include only the author's ID.
       def mentions_timeline(options = {})
-        perform_get_with_objects("/1.1/statuses/mentions_timeline.json", options, Twitter::Tweet)
+        perform_get_with_objects("/1.1/statuses/mentions_timeline.json", options, Tweet)
       end
-      alias mentions mentions_timeline
+      # @!method mentions
+      #   @api public
+      #   @see #mentions_timeline
+      alias_method :mentions, :mentions_timeline
 
       # Returns the 20 most recent Tweets posted by the specified user
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/statuses/user_timeline
       # @note This method can only return up to 3,200 Tweets.
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.user_timeline('sferik')
       # @return [Array<Twitter::Tweet>]
       # @overload user_timeline(user, options = {})
       #   @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
@@ -46,113 +59,135 @@ module Twitter
       #   @option options [Boolean, String, Integer] :contributor_details Specifies that the contributors element should be enhanced to include the screen_name of the contributor.
       #   @option options [Boolean, String, Integer] :include_rts Specifies that the timeline should include native retweets in addition to regular tweets. Note: If you're using the trim_user parameter in conjunction with include_rts, the retweets will no longer contain a full user object.
       def user_timeline(*args)
-        objects_from_response_with_user(Twitter::Tweet, :get, "/1.1/statuses/user_timeline.json", args)
+        objects_from_response_with_user(Tweet, :get, "/1.1/statuses/user_timeline.json", args)
       end
 
       # Returns the 20 most recent retweets posted by the specified user
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/statuses/user_timeline
       # @note This method can only return up to 3,200 Tweets.
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.retweeted_by_user('sferik')
       # @return [Array<Twitter::Tweet>]
       # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
       # @param options [Hash] A customizable set of options.
-      # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
-      # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
-      # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200.
-      # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1.
-      # @option options [Boolean, String, Integer] :exclude_replies This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets - this is because the count parameter retrieves that many tweets before filtering out retweets and replies.
-      # @option options [Boolean, String, Integer] :contributor_details Specifies that the contributors element should be enhanced to include the screen_name of the contributor.
+      # @option options [Integer] :since_id Returns results with an ID greater than the specified ID.
+      # @option options [Integer] :max_id Returns results with an ID less than the specified ID.
+      # @option options [Integer] :count Specifies the number of records to retrieve.
+      # @option options [Boolean, String, Integer] :trim_user Include only the author's ID.
+      # @option options [Boolean, String, Integer] :exclude_replies Exclude replies from results.
+      # @option options [Boolean, String, Integer] :contributor_details Include contributor screen names.
       def retweeted_by_user(user, options = {})
         retweets_from_timeline(options) do |opts|
           user_timeline(user, opts)
         end
       end
-      alias retweeted_by retweeted_by_user
+      # @!method retweeted_by
+      #   @api public
+      #   @see #retweeted_by_user
+      alias_method :retweeted_by, :retweeted_by_user
 
       # Returns the 20 most recent retweets posted by the authenticating user
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/statuses/user_timeline
       # @note This method can only return up to 3,200 Tweets.
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.retweeted_by_me
       # @return [Array<Twitter::Tweet>]
       # @param options [Hash] A customizable set of options.
-      # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
-      # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
-      # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200.
-      # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1.
-      # @option options [Boolean, String, Integer] :exclude_replies This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets - this is because the count parameter retrieves that many tweets before filtering out retweets and replies.
-      # @option options [Boolean, String, Integer] :contributor_details Specifies that the contributors element should be enhanced to include the screen_name of the contributor.
+      # @option options [Integer] :since_id Returns results with an ID greater than the specified ID.
+      # @option options [Integer] :max_id Returns results with an ID less than the specified ID.
+      # @option options [Integer] :count Specifies the number of records to retrieve.
+      # @option options [Boolean, String, Integer] :trim_user Include only the author's ID.
+      # @option options [Boolean, String, Integer] :exclude_replies Exclude replies from results.
+      # @option options [Boolean, String, Integer] :contributor_details Include contributor screen names.
       def retweeted_by_me(options = {})
         retweets_from_timeline(options) do |opts|
           user_timeline(opts)
         end
       end
 
-      # Returns the 20 most recent Tweets, including retweets if they exist, posted by the authenticating user and the users they follow
+      # Returns the 20 most recent Tweets from the authenticating user's timeline
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/statuses/home_timeline
       # @note This method can only return up to 800 Tweets, including retweets.
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.home_timeline
       # @return [Array<Twitter::Tweet>]
       # @param options [Hash] A customizable set of options.
-      # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
-      # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
-      # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200.
-      # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1.
-      # @option options [Boolean, String, Integer] :exclude_replies This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets - this is because the count parameter retrieves that many tweets before filtering out retweets and replies.
-      # @option options [Boolean, String, Integer] :include_rts Specifies that the timeline should include native retweets in addition to regular tweets. Note: If you're using the trim_user parameter in conjunction with include_rts, the retweets will no longer contain a full user object.
-      # @option options [Boolean, String, Integer] :contributor_details Specifies that the contributors element should be enhanced to include the screen_name of the contributor.
+      # @option options [Integer] :since_id Returns results with an ID greater than the specified ID.
+      # @option options [Integer] :max_id Returns results with an ID less than the specified ID.
+      # @option options [Integer] :count Specifies the number of records to retrieve.
+      # @option options [Boolean, String, Integer] :trim_user Include only the author's ID.
+      # @option options [Boolean, String, Integer] :exclude_replies Exclude replies from results.
+      # @option options [Boolean, String, Integer] :include_rts Include native retweets.
+      # @option options [Boolean, String, Integer] :contributor_details Include contributor screen names.
       def home_timeline(options = {})
-        perform_get_with_objects("/1.1/statuses/home_timeline.json", options, Twitter::Tweet)
+        perform_get_with_objects("/1.1/statuses/home_timeline.json", options, Tweet)
       end
 
-      # Returns the 20 most recent retweets posted by users the authenticating user follow.
+      # Returns the 20 most recent retweets posted by followed users
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/statuses/home_timeline
       # @note This method can only return up to 800 Tweets, including retweets.
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.retweeted_to_me
       # @return [Array<Twitter::Tweet>]
       # @param options [Hash] A customizable set of options.
-      # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
-      # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
-      # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200.
-      # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1.
-      # @option options [Boolean, String, Integer] :exclude_replies This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets - this is because the count parameter retrieves that many tweets before filtering out retweets and replies.
-      # @option options [Boolean, String, Integer] :contributor_details Specifies that the contributors element should be enhanced to include the screen_name of the contributor.
+      # @option options [Integer] :since_id Returns results with an ID greater than the specified ID.
+      # @option options [Integer] :max_id Returns results with an ID less than the specified ID.
+      # @option options [Integer] :count Specifies the number of records to retrieve.
+      # @option options [Boolean, String, Integer] :trim_user Include only the author's ID.
+      # @option options [Boolean, String, Integer] :exclude_replies Exclude replies from results.
+      # @option options [Boolean, String, Integer] :contributor_details Include contributor screen names.
       def retweeted_to_me(options = {})
         retweets_from_timeline(options) do |opts|
           home_timeline(opts)
         end
       end
 
-      # Returns the 20 most recent tweets of the authenticated user that have been retweeted by others
+      # Returns the 20 most recent tweets that have been retweeted by others
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/statuses/retweets_of_me
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.retweets_of_me
       # @return [Array<Twitter::Tweet>]
       # @param options [Hash] A customizable set of options.
-      # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200.
-      # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
-      # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
-      # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1.
-      # @option options [Boolean, String, Integer] :include_user_entities The user entities node will be disincluded when set to false.
+      # @option options [Integer] :count Specifies the number of records to retrieve.
+      # @option options [Integer] :since_id Returns results with an ID greater than the specified ID.
+      # @option options [Integer] :max_id Returns results with an ID less than the specified ID.
+      # @option options [Boolean, String, Integer] :trim_user Include only the author's ID.
+      # @option options [Boolean, String, Integer] :include_user_entities Include user entities.
       def retweets_of_me(options = {})
-        perform_get_with_objects("/1.1/statuses/retweets_of_me.json", options, Twitter::Tweet)
+        perform_get_with_objects("/1.1/statuses/retweets_of_me.json", options, Tweet)
       end
 
-    private
+      private
 
+      # Retrieves retweets from a timeline
+      #
+      # @api private
+      # @return [Array<Twitter::Tweet>]
       def retweets_from_timeline(options)
         options[:include_rts] = true
         count = options[:count] || DEFAULT_TWEETS_PER_REQUEST
@@ -161,16 +196,20 @@ module Twitter
         end
       end
 
-      # @param tweets [Array]
+      # Selects retweets from a collection of tweets
+      #
+      # @api private
       # @return [Array<Twitter::Tweet>]
       def select_retweets(tweets)
         tweets.select(&:retweet?)
       end
 
-      # @param count [Integer]
+      # Collects tweets up to a specified count
+      #
+      # @api private
       # @return [Array<Twitter::Tweet>]
       def collect_with_count(count)
-        options = {}
+        options = {} # : Hash[Symbol, untyped]
         options[:count] = MAX_TWEETS_PER_REQUEST
         collect_with_max_id do |max_id|
           options[:max_id] = max_id unless max_id.nil?
@@ -179,18 +218,19 @@ module Twitter
             count -= tweets.length
             tweets
           end
-        end.flatten.compact[0...count]
+        end[nil...count]
       end
 
-      # @param collection [Array]
-      # @param max_id [Integer, NilClass]
+      # Collects tweets using max_id pagination
+      #
+      # @api private
       # @return [Array<Twitter::Tweet>]
       def collect_with_max_id(collection = [], max_id = nil, &)
         tweets = yield(max_id)
         return collection if tweets.nil?
 
         collection += tweets
-        tweets.empty? ? collection.flatten : collect_with_max_id(collection, tweets.last.id - 1, &)
+        tweets.empty? ? collection : collect_with_max_id(collection, tweets.last.id - 1, &) # steep:ignore NoMethod
       end
     end
   end

data/lib/twitter/rest/trends.rb

@@ -5,53 +5,72 @@ require "twitter/trend_results"
 
 module Twitter
   module REST
+    # Methods for accessing trending topics
     module Trends
       include Twitter::REST::Utils
 
       # Returns the top 50 trending topics for a specific WOEID
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/trends/place
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
-      # @param id [Integer] The {https://developer.yahoo.com/geo/geoplanet Yahoo! Where On Earth ID} of the location to return trending information for. WOEIDs can be retrieved by calling {Twitter::REST::Trends#trends_available}. Global information is available by using 1 as the WOEID.
+      # @example
+      #   client.trends
+      # @param id [Integer] The Yahoo! Where On Earth ID of the location.
       # @param options [Hash] A customizable set of options.
-      # @option options [String] :exclude Setting this equal to 'hashtags' will remove all hashtags from the trends list.
+      # @option options [String] :exclude Setting this equal to 'hashtags' excludes hashtags.
       # @return [Array<Twitter::Trend>]
       def trends(id = 1, options = {})
         options = options.dup
         options[:id] = id
         response = perform_get("/1.1/trends/place.json", options).first
-        Twitter::TrendResults.new(response)
+        TrendResults.new(response)
       end
-      alias local_trends trends
-      alias trends_place trends
+      # @!method local_trends
+      #   @api public
+      #   @see #trends
+      alias_method :local_trends, :trends
+      # @!method trends_place
+      #   @api public
+      #   @see #trends
+      alias_method :trends_place, :trends
 
-      # Returns the locations that Twitter has trending topic information for
+      # Returns locations with trending topic information
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/trends/available
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.trends_available
       # @param options [Hash] A customizable set of options.
       # @return [Array<Twitter::Place>]
       def trends_available(options = {})
-        perform_get_with_objects("/1.1/trends/available.json", options, Twitter::Place)
+        perform_get_with_objects("/1.1/trends/available.json", options, Place)
       end
-      alias trend_locations trends_available
+      # @!method trend_locations
+      #   @api public
+      #   @see #trends_available
+      alias_method :trend_locations, :trends_available
 
-      # Returns the locations that Twitter has trending topic information for, closest to a specified location.
+      # Returns trend locations closest to a specified location
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/trends/closest
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.trends_closest(lat: 37.7821, long: -122.4093)
       # @param options [Hash] A customizable set of options.
-      # @option options [Float] :lat If provided with a :long option the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for latitude are -90.0 to +90.0 (North is positive) inclusive.
-      # @option options [Float] :long If provided with a :lat option the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for longitude are -180.0 to +180.0 (East is positive) inclusive.
+      # @option options [Float] :lat The latitude to search around.
+      # @option options [Float] :long The longitude to search around.
       # @return [Array<Twitter::Place>]
       def trends_closest(options = {})
-        perform_get_with_objects("/1.1/trends/closest.json", options, Twitter::Place)
+        perform_get_with_objects("/1.1/trends/closest.json", options, Place)
       end
     end
   end