Update and improve documentation for API.search_users

Automatically use docstring for documentation
Improve method and documentation order
Add include_entities parameter to documentation
Improve parameter order in documentation
Fix documentation for count parameter by using substitution

diff --git a/docs/api.rst b/docs/api.rst
index 9fda16f795d2da38fa87e97327d10bc51b922a83..5c0706b822c98b83c62213dd4f39417bfc8b7331 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -131,6 +131,8 @@ Follow, search, and get users
 
 .. automethod:: API.lookup_users
 
+.. automethod:: API.search_users
+
 
 User methods
 ------------
@@ -152,20 +154,6 @@ User methods
    :rtype: :class:`User` object
 
 
-.. method:: API.search_users(q, [count], [page])
-
-   Run a search for users similar to Find People button on Twitter.com; the
-   same results returned by people search on Twitter.com will be returned by
-   using this API (about being listed in the People Search). It is only
-   possible to retrieve the first 1000 matches from this API.
-
-   :param q: The query to run against people search.
-   :param count: Specifies the number of statuses to retrieve.
-                 May not be greater than 20.
-   :param page: |page|
-   :rtype: list of :class:`User` objects
-
-
 Direct Message Methods
 ----------------------
 

diff --git a/tweepy/api.py b/tweepy/api.py
index 1be06b22980c97a1a63f4e0d27531e7def8ab702..229e399dbe2330c1a413e180e3684b5ad50f5c26 100644 (file)
--- a/tweepy/api.py
+++ b/tweepy/api.py
@@ -1631,6 +1631,31 @@ class API:
             user_id=list_to_csv(user_id), **kwargs
         )
 
+    @pagination(mode='page')
+    @payload('user', list=True)
+    def search_users(self, q, **kwargs):
+        """search_users(q, *, page, count, include_entities)
+
+        Run a search for users similar to Find People button on Twitter.com;
+        the same results returned by people search on Twitter.com will be
+        returned by using this API (about being listed in the People Search).
+        It is only possible to retrieve the first 1000 matches from this API.
+
+        :param q: The query to run against people search.
+        :param page: |page|
+        :param count: |count|
+        :param include_entities: |include_entities|
+
+        :rtype: list of :class:`User` objects
+
+        :reference: https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-search
+        """
+        return self.request(
+            'GET', 'users/search', endpoint_parameters=(
+                'q', 'page', 'count', 'include_entities'
+            ), q=q, **kwargs
+        )
+
     def media_upload(self, filename, *, file=None, chunked=False,
                      media_category=None, additional_owners=None, **kwargs):
         """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/overview
@@ -1812,17 +1837,6 @@ class API:
         """ Get the authenticated user """
         return self.get_user(screen_name=self.auth.get_username())
 
-    @pagination(mode='page')
-    @payload('user', list=True)
-    def search_users(self, q, **kwargs):
-        """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-search
-        """
-        return self.request(
-            'GET', 'users/search', endpoint_parameters=(
-                'q', 'page', 'count', 'include_entities'
-            ), q=q, **kwargs
-        )
-
     @payload('direct_message')
     def get_direct_message(self, id, **kwargs):
         """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/direct-messages/sending-and-receiving/api-reference/get-event