Update and improve documentation for API.reverse_geocode

Automatically use docstring for documentation
Improve method and documentation order
Add API documentation header to match API reference index
Update method/endpoint documentation
Add return type to documentation

diff --git a/docs/api.rst b/docs/api.rst
index 00850aa70cad06ae0c404ecabe65e671f5991150..729b743fbfb2f22328096cc9eb66f2b67da08581 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -248,6 +248,11 @@ Get information about a place
 
 .. automethod:: API.geo_id
 
+Get places near a location
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automethod:: API.reverse_geocode
+
 
 Account Methods
 ---------------
@@ -361,30 +366,6 @@ Search Methods
       provided by the API, and should not be modified.
 
 
-Geo Methods
------------
-
-.. method:: API.reverse_geocode([lat], [long], [accuracy], [granularity], \
-                                [max_results])
-
-   Given a latitude and longitude, looks for places (cities and neighbourhoods)
-   whose IDs can be specified in a call to :func:`update_status` to appear as
-   the name of the location. This call provides a detailed response about the
-   location in question; the :func:`nearby_places` function should be preferred
-   for getting a list of places nearby without great detail.
-
-   :param lat: The location's latitude.
-   :param long: The location's longitude.
-   :param accuracy: Specify the "region" in which to search, such as 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
-   :param granularity: Assumed to be ``neighborhood`` by default; can also be
-                       ``city``.
-   :param max_results: A hint as to the maximum number of results to return.
-                       This is only a guideline, which may not be adhered to.
-
-
 Utility methods
 ---------------
 

diff --git a/tweepy/api.py b/tweepy/api.py
index 54c9dbf7f4d927b97aafc9bce51a322a0e8e2ace..2153c4fe93ce104d1a53e9a51cf96506c895bb48 100644 (file)
--- a/tweepy/api.py
+++ b/tweepy/api.py
@@ -2676,6 +2676,39 @@ class API:
         """
         return self.request('GET', f'geo/id/{place_id}', **kwargs)
 
+    # Get places near a location
+
+    @payload('place', list=True)
+    def reverse_geocode(self, lat, long, **kwargs):
+        """reverse_geocode(lat, long, *, accuracy, granularity, max_results)
+
+        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.
+
+        :param lat: The location's latitude.
+        :param long: The location's longitude.
+        :param accuracy: Specify the "region" in which to search, such as 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
+        :param granularity: Assumed to be ``neighborhood`` by default; can also
+                            be ``city``.
+        :param max_results: A hint as to the maximum number of results to
+            return. This is only a guideline, which may not be adhered to.
+
+        :rtype: list of :class:`Place` objects
+
+        :reference: https://developer.twitter.com/en/docs/twitter-api/v1/geo/places-near-location/api-reference/get-geo-reverse_geocode
+        """
+        return self.request(
+            'GET', 'geo/reverse_geocode', endpoint_parameters=(
+                'lat', 'long', 'accuracy', 'granularity', 'max_results'
+            ), lat=lat, long=long, **kwargs
+        )
+
     @payload('json')
     def rate_limit_status(self, **kwargs):
         """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/developer-utilities/rate-limit-status/api-reference/get-application-rate_limit_status
@@ -2708,16 +2741,6 @@ class API:
             ), query=query, **kwargs
         )
 
-    @payload('place', list=True)
-    def reverse_geocode(self, lat, long, **kwargs):
-        """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/geo/places-near-location/api-reference/get-geo-reverse_geocode
-        """
-        return self.request(
-            'GET', 'geo/reverse_geocode', endpoint_parameters=(
-                'lat', 'long', 'accuracy', 'granularity', 'max_results'
-            ), lat=lat, long=long, **kwargs
-        )
-
     @payload('place', list=True)
     def geo_search(self, **kwargs):
         """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/geo/places-near-location/api-reference/get-geo-search