Improve documentation for API.lookup_users

diff --git a/docs/api.rst b/docs/api.rst
index 880d46c0a88930c262302cd8f1726b6e8c4ddeb3..fe139456ce41ff2ebbd9eb9023499e2b76082f5e 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -333,22 +333,22 @@ User methods
    :rtype: list of :class:`User` objects
 
 
-.. method:: API.search_users(q, [count], [page])
+.. method:: API.lookup_users([user_ids], [screen_names], [include_entities], \
+                             [tweet_mode])
 
-   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.
+   Returns fully-hydrated user objects for up to 100 users per request.
 
-   :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
+   There are a few things to note when using this method.
 
-
-.. method:: API.lookup_users([user_ids], [screen_names], [include_entities], \
-                             [tweet_mode])
+   * You must be following a protected user to be able to see their most recent
+     status update. If you don't follow a protected user their status will be
+     removed.
+   * The order of user IDs or screen names may not match the order of users in
+     the returned array.
+   * If a requested user is unknown, suspended, or deleted, then that user will
+     not be returned in the results list.
+   * If none of your lookup criteria can be satisfied by returning a user
+     object, a HTTP 404 will be thrown.
 
    :param user_ids: A list of user IDs, up to 100 are allowed in a single
                     request.
@@ -361,6 +361,20 @@ User methods
    :rtype: list of :class:`User` objects
 
 
+.. 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
 ----------------------