Add documentation for search and trends

.yardopts

@@ -1,6 +1,7 @@
 --protected
+--tag formats:"Supported formats"
 --tag authenticated:"Requires Authentication"
---tag rate_limited:"Rate limited"
+--tag rate_limited:"Rate Limited"
 -
 LICENSE.md
 HISTORY.md

lib/twitter/client/geo.rb

@@ -1,23 +1,101 @@
 module Twitter
   class Client
+    # @see http://dev.twitter.com/pages/geo_dev_guidelines Twitter Geo Developer Guidelines
     module Geo
+      # Search for places that can be attached to a {Twitter::Client::Tweets#update}.
+      # Given a latitude and a longitude pair, an IP address, or a name, this request
+      # will return a list of all the valid places that can be used as the place_id
+      # when updating a status.
+      #
+      # @formats :json
+      # @authenticated false
+      # @rate_limited true
+      # @param options [Hash] A customizable set of options.
+      # @option options [Float] :lat The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding :long option.
+      # @option options [Float] :long The longitude to search around. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.
+      # @option options [String] :query Free-form text to match against while executing a geo-based query, best suited for finding nearby locations by name.
+      # @option options [String] :ip An IP address. Used when attempting to fix geolocation based off of the user's IP address.
+      # @option options [String] :granularity This is the minimal granularity of place types to return and must be one of: 'poi', 'neighborhood', 'city', 'admin' or 'country'. If no granularity is provided for the request neighborhood is assumed.
+      # @option options [String] :accuracy A hint on the "region" in which to search. If a number, then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet. If this is not passed in, then it is assumed to be 0m. If coming from a device, in practice, this value is whatever accuracy the device has measuring its location (whether it be coming from a GPS, WiFi triangulation, etc.).
+      # @option options [Integer] :max_results A hint as to the number of results to return. This does not guarantee that the number of results returned will equal max_results, but instead informs how many "nearby" results to return. Ideally, only pass in the number of places you intend to display to the user here.
+      # @option options [String] :contained_within This is the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found.
+      # @option options [String] :"attribute:street_address" This option searches for places which have this given street address. There are other well-known, and application specific attributes available. Custom attributes are also permitted.
+      # @return [Array]
+      # @see http://dev.twitter.com/doc/get/geo/search
       def places_nearby(options={})
         get('geo/search', options)['result']['places']
       end
       alias :geo_search :places_nearby
 
+      # Locates places near the given coordinates which are similar in name.
+      #
+      # Conceptually you would use this method to get a list of known places to choose from first.
+      # Then, if the desired place doesn't exist, make a request to {Twitter::Client::Geo#place}
+      # to create a new one.
+      #
+      # The token contained in the response is the token needed to be able to create a new place.
+      #
+      # @formats :json
+      # @authenticated false
+      # @rate_limited true
+      # @param options [Hash] A customizable set of options.
+      # @option options [Float] :lat The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding :long option.
+      # @option options [Float] :long The longitude to search around. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.
+      # @option options [String] :name The name a place is known as.
+      # @option options [String] :contained_within This is the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found.
+      # @option options [String] :"attribute:street_address" This option searches for places which have this given street address. There are other well-known, and application specific attributes available. Custom attributes are also permitted.
+      # @return [Array]
+      # @see http://dev.twitter.com/doc/get/geo/similar_places
       def places_similar(options={})
         get('geo/similar_places', options)['result']['places']
       end
 
+      # Given a latitude and a longitude, searches for up to 20 places that can be used as a place_id when updating a status.
+      #
+      # This request is an informative call and will deliver generalized results about geography.
+      #
+      # @formats :json
+      # @authenticated false
+      # @rate_limited true
+      # @param options [Hash] A customizable set of options.
+      # @option options [Float] :lat The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding :long option.
+      # @option options [Float] :long The longitude to search around. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.
+      # @option options [String] :accuracy A hint on the "region" in which to search. If a number, then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet. If this is not passed in, then it is assumed to be 0m. If coming from a device, in practice, this value is whatever accuracy the device has measuring its location (whether it be coming from a GPS, WiFi triangulation, etc.).
+      # @option options [String] :granularity This is the minimal granularity of place types to return and must be one of: 'poi', 'neighborhood', 'city', 'admin' or 'country'. If no granularity is provided for the request neighborhood is assumed.
+      # @option options [Integer] :max_results A hint as to the number of results to return. This does not guarantee that the number of results returned will equal max_results, but instead informs how many "nearby" results to return. Ideally, only pass in the number of places you intend to display to the user here.
+      # @return [Array]
+      # @see http://dev.twitter.com/doc/get/geo/reverse_geocode
       def reverse_geocode(options={})
         get('geo/reverse_geocode', options)['result']['places']
       end
 
-      def place(id, options={})
-        get("geo/id/#{id}", options)
+      # Returns all the information about a known place
+      #
+      # @formats :json
+      # @authenticated false
+      # @rate_limited true
+      # @param place_id [String] A place in the world. These IDs can be retrieved from {Twitter::Client::Geo#reverse_geocode}.
+      # @param options [Hash] A customizable set of options.
+      # @return [Hashie::Mash]
+      # @see http://dev.twitter.com/doc/get/geo/id/:place_id
+      def place(place_id, options={})
+        get("geo/id/#{place_id}", options)
       end
 
+      # Creates a new place at the given latitude and longitude
+      #
+      # @formats :json
+      # @authenticated false
+      # @rate_limited true
+      # @param options [Hash] A customizable set of options.
+      # @option options [String] :name The name a place is known as.
+      # @option options [String] :contained_within This is the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found.
+      # @option options [String] :token The token found in the response from {Twitter::Client::Geo#places_similar}.
+      # @option options [Float] :lat The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding :long option.
+      # @option options [Float] :long The longitude to search around. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.
+      # @option options [String] :"attribute:street_address" This option searches for places which have this given street address. There are other well-known, and application specific attributes available. Custom attributes are also permitted.
+      # @return [Hashie::Mash]
+      # @see http://dev.twitter.com/doc/post/geo/place
       def place_create(options={})
         post('geo/place', options)
       end

lib/twitter/client/local_trends.rb

@@ -1,11 +1,41 @@
 module Twitter
   class Client
     module LocalTrends
+      # Returns the locations that Twitter has trending topic information for.
+      #
+      # The response is an array of "locations" that encode the location's WOEID and some other human-readable information
+      # such as a canonical name and country the location belongs in.
+      #
+      # A WOEID is a {http://developer.yahoo.com/geo/geoplanet Yahoo! Where On Earth ID}.
+      #
+      # @formats :json, :xml
+      # @authenticated false
+      # @rate_limited true
+      # @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 is -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 is -180.0 to +180.0 (East is positive) inclusive.
+      # @return [Array]
+      # @see http://dev.twitter.com/doc/get/trends/available
       def trend_locations(options={})
         response = get('trends/available', options)
         format.to_s.downcase == 'xml' ? response['locations'] : response
       end
 
+      # Returns the top 10 trending topics for a specific WOEID, if trending information is available for it.
+      #
+      # The response is an array of "trend" objects that encode the name of the trending topic, the query option that can be
+      # used to search for the topic on {http://search.twitter.com Twitter Search}, and the Twitter Search URL.
+      #
+      # This information is cached for 5 minutes. Requesting more frequently than that will not return any more data, and will
+      # count against your rate limit usage.
+      #
+      # @formats :json, :xml
+      # @authenticated false
+      # @rate_limited true
+      # @param woeid [Integer] The {http://developer.yahoo.com/geo/geoplanet Yahoo! Where On Earth ID} of the location to return trending information for. Global information is available by using 1 as the WOEID.
+      # @param options [Hash] A customizable set of options.
+      # @return [Array]
+      # @see http://dev.twitter.com/doc/get/trends/:woeid
       def local_trends(woeid=1, options={})
         response = get("trends/#{woeid}", options)
         format.to_s.downcase == 'xml' ? response['matching_trends'].first.trend : response.first.trends.map{|trend| trend.name}

lib/twitter/client/trends.rb

@@ -1,18 +1,57 @@
 module Twitter
   class Client
     module Trends
+      # Returns the top ten topics that are currently trending on Twitter. The response includes the time of the request,
+      # the name of each trend, and the url to the {http://search.twitter.com Twitter Search} results page for that topic.
+      #
+      # @formats :json
+      # @authenticated false
+      # @rate_limited true
+      # @param options [Hash] A customizable set of options.
+      # @return [Array]
+      # @see http://dev.twitter.com/doc/get/trends
       def trends(options={})
         get('trends', options)['trends']
       end
 
+      # Returns the current top 10 trending topics on Twitter. The response includes the time of the request,
+      # the name of each trending topic, and query used on {http://search.twitter.com Twitter Search} results page for that topic.
+      #
+      # @formats :json
+      # @authenticated false
+      # @rate_limited true
+      # @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.
+      # @return [Array]
+      # @see http://dev.twitter.com/doc/get/trends/current
       def trends_current(options={})
         get('trends/current', options)['trends']
       end
 
+      # Returns the top 20 trending topics for each hour in a given day.
+      #
+      # @formats :json
+      # @authenticated false
+      # @rate_limited true
+      # @param date [String] The start date for the report. The date should be formatted YYYY-MM-DD. A 404 error will be thrown if the date is older than the available search index (7-10 days). Dates in the future will be forced to the current date.
+      # @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.
+      # @return [Array]
+      # @see http://dev.twitter.com/doc/get/trends/daily
       def trends_daily(date=Time.now, options={})
         get('trends/daily', options.merge(:date => date.strftime('%Y-%m-%d')))['trends']
       end
 
+      # Returns the top 30 trending topics for each day in a given week.
+      #
+      # @formats :json
+      # @authenticated false
+      # @rate_limited true
+      # @param date [String] The start date for the report. The date should be formatted YYYY-MM-DD. A 404 error will be thrown if the date is older than the available search index (7-10 days). Dates in the future will be forced to the current date.
+      # @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.
+      # @return [Array]
+      # @see http://dev.twitter.com/doc/get/trends/weekly
       def trends_weekly(date=Time.now, options={})
         get('trends/weekly', options.merge(:date => date.strftime('%Y-%m-%d')))['trends']
       end