From b6ea451ee5db710fdf562c18cba11c37f1f67b7a Mon Sep 17 00:00:00 2001
From: Dan <14043624+delivrance@users.noreply.github.com>
Date: Fri, 17 May 2019 13:44:44 +0200
Subject: [PATCH] Reword some method return type docstrings

---
 docs/source/api/handlers.rst                     | 16 ----------------
 docs/source/api/methods.rst                      |  2 --
 docs/source/api/types.rst                        |  2 ++
 docs/source/index.rst                            |  2 +-
 docs/source/intro/start.rst                      |  2 +-
 docs/source/topics/advanced-usage.rst            |  2 +-
 .../client/methods/bots/answer_inline_query.py   |  2 +-
 .../methods/bots/send_inline_bot_result.py       |  2 +-
 pyrogram/client/methods/bots/set_game_score.py   |  6 +++---
 .../methods/chats/get_chat_members_count.py      |  2 +-
 .../client/methods/chats/get_dialogs_count.py    |  2 +-
 .../client/methods/chats/kick_chat_member.py     |  5 ++---
 pyrogram/client/methods/contacts/get_contacts.py |  1 +
 .../methods/contacts/get_contacts_count.py       |  2 +-
 .../client/methods/messages/download_media.py    |  5 ++---
 .../messages/edit_message_reply_markup.py        |  5 ++---
 .../client/methods/messages/forward_messages.py  |  8 +++-----
 .../client/methods/messages/get_history_count.py |  2 +-
 pyrogram/client/methods/messages/get_messages.py |  8 +++-----
 .../client/methods/messages/send_animation.py    |  5 ++---
 pyrogram/client/methods/messages/send_audio.py   |  5 ++---
 .../client/methods/messages/send_document.py     |  5 ++---
 pyrogram/client/methods/messages/send_photo.py   |  5 ++---
 pyrogram/client/methods/messages/send_sticker.py |  6 ++----
 pyrogram/client/methods/messages/send_video.py   |  5 ++---
 .../client/methods/messages/send_video_note.py   |  5 ++---
 pyrogram/client/methods/messages/send_voice.py   |  5 ++---
 .../users/get_user_profile_photos_count.py       |  2 +-
 pyrogram/client/methods/users/get_users.py       |  7 ++++---
 29 files changed, 48 insertions(+), 78 deletions(-)

diff --git a/docs/source/api/handlers.rst b/docs/source/api/handlers.rst
index 023f6e28..5f80922d 100644
--- a/docs/source/api/handlers.rst
+++ b/docs/source/api/handlers.rst
@@ -38,26 +38,10 @@ it.
     RawUpdateHandler
 
 .. autoclass:: MessageHandler()
-    :members:
-
 .. autoclass:: DeletedMessagesHandler()
-    :members:
-
 .. autoclass:: CallbackQueryHandler()
-    :members:
-
 .. autoclass:: InlineQueryHandler()
-    :members:
-
 .. autoclass:: UserStatusHandler()
-    :members:
-
 .. autoclass:: PollHandler()
-    :members:
-
 .. autoclass:: DisconnectHandler()
-    :members:
-
 .. autoclass:: RawUpdateHandler()
-    :members:
-
diff --git a/docs/source/api/methods.rst b/docs/source/api/methods.rst
index ded4d017..7c061d3a 100644
--- a/docs/source/api/methods.rst
+++ b/docs/source/api/methods.rst
@@ -90,7 +90,6 @@ Chats
     pin_chat_message
     unpin_chat_message
     get_chat
-    get_chat_preview
     get_chat_member
     get_chat_members
     get_chat_members_count
@@ -217,7 +216,6 @@ Bots
 .. automethod:: pyrogram.Client.pin_chat_message()
 .. automethod:: pyrogram.Client.unpin_chat_message()
 .. automethod:: pyrogram.Client.get_chat()
-.. automethod:: pyrogram.Client.get_chat_preview()
 .. automethod:: pyrogram.Client.get_chat_member()
 .. automethod:: pyrogram.Client.get_chat_members()
 .. automethod:: pyrogram.Client.get_chat_members_count()
diff --git a/docs/source/api/types.rst b/docs/source/api/types.rst
index 506fe003..d911520c 100644
--- a/docs/source/api/types.rst
+++ b/docs/source/api/types.rst
@@ -72,6 +72,7 @@ Keyboards
     ForceReply
     CallbackQuery
     GameHighScore
+    GameHighScores
     CallbackGame
 
 Input Media
@@ -155,6 +156,7 @@ InputMessageContent
 .. autoclass:: ForceReply()
 .. autoclass:: CallbackQuery()
 .. autoclass:: GameHighScore()
+.. autoclass:: GameHighScores()
 .. autoclass:: CallbackGame()
 
 ..  Input Media
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 9b878baf..d061b677 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -17,7 +17,7 @@ Welcome to Pyrogram
             GitHub
         </a>
         •
-        <a href="https://t.me/PyrogramChat">
+        <a href="https://t.me/Pyrogram">
             Community
         </a>
 
diff --git a/docs/source/intro/start.rst b/docs/source/intro/start.rst
index 2fcd4633..c7bfc74a 100644
--- a/docs/source/intro/start.rst
+++ b/docs/source/intro/start.rst
@@ -44,5 +44,5 @@ In the next few pages of the introduction, we'll take a much more in-depth look
 
 Feeling eager to continue? You can take a shortcut to `Calling Methods`_ and come back later to learn some more details.
 
-.. _community: //t.me/pyrogramchat
+.. _community: //t.me/Pyrogram
 .. _Calling Methods: ../start/invoking
\ No newline at end of file
diff --git a/docs/source/topics/advanced-usage.rst b/docs/source/topics/advanced-usage.rst
index 02a3e3b6..4032783f 100644
--- a/docs/source/topics/advanced-usage.rst
+++ b/docs/source/topics/advanced-usage.rst
@@ -130,4 +130,4 @@ high-level method.
 .. _plenty of them: ../api/methods
 .. _raw functions: ../telegram/functions
 .. _raw types: ../telegram/types
-.. _Community: https://t.me/PyrogramChat
\ No newline at end of file
+.. _Community: https://t.me/Pyrogram
\ No newline at end of file
diff --git a/pyrogram/client/methods/bots/answer_inline_query.py b/pyrogram/client/methods/bots/answer_inline_query.py
index 62344f20..38ed99c3 100644
--- a/pyrogram/client/methods/bots/answer_inline_query.py
+++ b/pyrogram/client/methods/bots/answer_inline_query.py
@@ -73,7 +73,7 @@ class AnswerInlineQuery(BaseClient):
                 where they wanted to use the bot's inline capabilities.
 
         Returns:
-            ``bool``: On success, True is returned.
+            ``bool``: True, on success.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/bots/send_inline_bot_result.py b/pyrogram/client/methods/bots/send_inline_bot_result.py
index 031591db..411ab462 100644
--- a/pyrogram/client/methods/bots/send_inline_bot_result.py
+++ b/pyrogram/client/methods/bots/send_inline_bot_result.py
@@ -58,7 +58,7 @@ class SendInlineBotResult(BaseClient):
                 Sends the message with *via @bot* hidden.
 
         Returns:
-            On success, the sent Message is returned.
+            :obj:`Message`: On success, the sent inline result message is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/bots/set_game_score.py b/pyrogram/client/methods/bots/set_game_score.py
index 3b0e97e2..f9115b74 100644
--- a/pyrogram/client/methods/bots/set_game_score.py
+++ b/pyrogram/client/methods/bots/set_game_score.py
@@ -32,7 +32,7 @@ class SetGameScore(BaseClient):
         disable_edit_message: bool = None,
         chat_id: Union[int, str] = None,
         message_id: int = None
-    ):
+    ) -> Union["pyrogram.Message", bool]:
         # inline_message_id: str = None):  TODO Add inline_message_id
         """Set the score of the specified user in a game.
 
@@ -63,8 +63,8 @@ class SetGameScore(BaseClient):
                 Required if inline_message_id is not specified.
 
         Returns:
-            On success, if the message was sent by the bot, returns the edited :obj:`Message`,
-            otherwise returns True.
+            :obj:`Message` | ``bool``: On success, if the message was sent by the bot, the edited message is returned,
+            True otherwise.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/chats/get_chat_members_count.py b/pyrogram/client/methods/chats/get_chat_members_count.py
index c8bd6deb..4c7ab747 100644
--- a/pyrogram/client/methods/chats/get_chat_members_count.py
+++ b/pyrogram/client/methods/chats/get_chat_members_count.py
@@ -34,7 +34,7 @@ class GetChatMembersCount(BaseClient):
                 Unique identifier (int) or username (str) of the target chat.
 
         Returns:
-            On success, an integer is returned.
+            ``int``: On success, the chat members count is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/chats/get_dialogs_count.py b/pyrogram/client/methods/chats/get_dialogs_count.py
index 1a307433..b9b0970a 100644
--- a/pyrogram/client/methods/chats/get_dialogs_count.py
+++ b/pyrogram/client/methods/chats/get_dialogs_count.py
@@ -29,7 +29,7 @@ class GetDialogsCount(BaseClient):
             Defaults to False.
 
         Returns:
-            ``int``: On success, an integer is returned.
+            ``int``: On success, the dialogs count is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/chats/kick_chat_member.py b/pyrogram/client/methods/chats/kick_chat_member.py
index f5058829..9686e754 100644
--- a/pyrogram/client/methods/chats/kick_chat_member.py
+++ b/pyrogram/client/methods/chats/kick_chat_member.py
@@ -54,9 +54,8 @@ class KickChatMember(BaseClient):
                 considered to be banned forever. Defaults to 0 (ban forever).
 
         Returns:
-            :obj:`Message`: On success, a service message will be returned (when applicable).
-
-            ``bool`` -- True, in case a message object couldn't be returned.
+            :obj:`Message` | ``bool``: On success, a service message will be returned (when applicable), otherwise, in
+            case a message object couldn't be returned, True is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/contacts/get_contacts.py b/pyrogram/client/methods/contacts/get_contacts.py
index 1fa5b738..0c231670 100644
--- a/pyrogram/client/methods/contacts/get_contacts.py
+++ b/pyrogram/client/methods/contacts/get_contacts.py
@@ -30,6 +30,7 @@ log = logging.getLogger(__name__)
 
 class GetContacts(BaseClient):
     def get_contacts(self) -> List["pyrogram.User"]:
+        # TODO: Create a Users object and return that
         """Get contacts from your Telegram address book.
 
         Returns:
diff --git a/pyrogram/client/methods/contacts/get_contacts_count.py b/pyrogram/client/methods/contacts/get_contacts_count.py
index 01fb0789..dddfe8c4 100644
--- a/pyrogram/client/methods/contacts/get_contacts_count.py
+++ b/pyrogram/client/methods/contacts/get_contacts_count.py
@@ -25,7 +25,7 @@ class GetContactsCount(BaseClient):
         """Get the total count of contacts from your Telegram address book.
 
         Returns:
-            ``int``: On success, an integer is returned.
+            ``int``: On success, the contacts count is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/messages/download_media.py b/pyrogram/client/methods/messages/download_media.py
index 5c440173..c21a95bf 100644
--- a/pyrogram/client/methods/messages/download_media.py
+++ b/pyrogram/client/methods/messages/download_media.py
@@ -73,9 +73,8 @@ class DownloadMedia(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            ``str``: On success, the absolute path of the downloaded file is returned.
-
-            ``None`` --  In case the download is deliberately stopped with :meth:`stop_transmission`.
+            ``str`` | ``None``: On success, the absolute path of the downloaded file is returned, otherwise, in case
+            the download failed or was deliberately stopped with :meth:`stop_transmission`, None is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/messages/edit_message_reply_markup.py b/pyrogram/client/methods/messages/edit_message_reply_markup.py
index 8d2b82af..a058646f 100644
--- a/pyrogram/client/methods/messages/edit_message_reply_markup.py
+++ b/pyrogram/client/methods/messages/edit_message_reply_markup.py
@@ -45,9 +45,8 @@ class EditMessageReplyMarkup(BaseClient):
                 An InlineKeyboardMarkup object.
 
         Returns:
-            :obj:`Message`: In case the edited message is sent by the bot.
-
-            ``bool`` -- True, in case the edited message is sent by the user.
+            :obj:`Message` | ``bool``: In case the edited message is sent by the bot, the edited message is returned,
+            otherwise, True is returned in case the edited message is send by the user.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/messages/forward_messages.py b/pyrogram/client/methods/messages/forward_messages.py
index 82c35f92..bc9ad331 100644
--- a/pyrogram/client/methods/messages/forward_messages.py
+++ b/pyrogram/client/methods/messages/forward_messages.py
@@ -64,11 +64,9 @@ class ForwardMessages(BaseClient):
                 Defaults to False.
 
         Returns:
-            :obj:`Message`: In case *message_ids* was an integer, the single forwarded message is
-            returned.
-
-            :obj:`Messages` -- In case *message_ids* was an iterable, the returned value will be an
-            object containing a list of messages, even if such iterable contained just a single element.
+            :obj:`Message` | :obj:`Messages`: In case *message_ids* was an integer, the single forwarded message is
+            returned, otherwise, in case *message_ids* was an iterable, the returned value will be an object containing
+            a list of messages, even if such iterable contained just a single element.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/messages/get_history_count.py b/pyrogram/client/methods/messages/get_history_count.py
index ced46799..48614030 100644
--- a/pyrogram/client/methods/messages/get_history_count.py
+++ b/pyrogram/client/methods/messages/get_history_count.py
@@ -45,7 +45,7 @@ class GetHistoryCount(BaseClient):
                 Unique identifier (int) or username (str) of the target chat.
 
         Returns:
-            ``int``: On success, an integer is returned.
+            ``int``: On success, the chat history count is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/messages/get_messages.py b/pyrogram/client/methods/messages/get_messages.py
index 51f71352..7a60f276 100644
--- a/pyrogram/client/methods/messages/get_messages.py
+++ b/pyrogram/client/methods/messages/get_messages.py
@@ -60,11 +60,9 @@ class GetMessages(BaseClient):
                 Defaults to 1.
 
         Returns:
-            :obj:`Message`: In case *message_ids* was an integer, the single forwarded message is
-            returned.
-
-            :obj:`Messages` -- In case *message_ids* was an iterable, the returned value will be an
-            object containing a list of messages, even if such iterable contained just a single element.
+            :obj:`Message` | :obj:`Messages`: In case *message_ids* was an integer, the single requested message is
+            returned, otherwise, in case *message_ids* was an iterable, the returned value will be an object containing
+            a list of messages, even if such iterable contained just a single element.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/messages/send_animation.py b/pyrogram/client/methods/messages/send_animation.py
index 461ef6fc..edf5ea54 100644
--- a/pyrogram/client/methods/messages/send_animation.py
+++ b/pyrogram/client/methods/messages/send_animation.py
@@ -120,9 +120,8 @@ class SendAnimation(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent animation message is returned.
-
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
+            :obj:`Message` | ``None``: On success, the sent animation message is returned, otherwise, in case the upload
+            is deliberately stopped with :meth:`stop_transmission`, None is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/messages/send_audio.py b/pyrogram/client/methods/messages/send_audio.py
index aaa5a529..b6d7b777 100644
--- a/pyrogram/client/methods/messages/send_audio.py
+++ b/pyrogram/client/methods/messages/send_audio.py
@@ -122,9 +122,8 @@ class SendAudio(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent audio message is returned.
-
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
+            :obj:`Message` | ``None``: On success, the sent audio message is returned, otherwise, in case the upload
+            is deliberately stopped with :meth:`stop_transmission`, None is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/messages/send_document.py b/pyrogram/client/methods/messages/send_document.py
index 66b3f1c9..df202fd7 100644
--- a/pyrogram/client/methods/messages/send_document.py
+++ b/pyrogram/client/methods/messages/send_document.py
@@ -108,9 +108,8 @@ class SendDocument(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent document message is returned.
-
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
+            :obj:`Message` | ``None``: On success, the sent document message is returned, otherwise, in case the upload
+            is deliberately stopped with :meth:`stop_transmission`, None is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/messages/send_photo.py b/pyrogram/client/methods/messages/send_photo.py
index 7c4f688f..14292da9 100644
--- a/pyrogram/client/methods/messages/send_photo.py
+++ b/pyrogram/client/methods/messages/send_photo.py
@@ -107,9 +107,8 @@ class SendPhoto(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent photo message is returned.
-
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
+            :obj:`Message` | ``None``: On success, the sent photo message is returned, otherwise, in case the upload
+            is deliberately stopped with :meth:`stop_transmission`, None is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/messages/send_sticker.py b/pyrogram/client/methods/messages/send_sticker.py
index cabe3487..4a03e4c8 100644
--- a/pyrogram/client/methods/messages/send_sticker.py
+++ b/pyrogram/client/methods/messages/send_sticker.py
@@ -92,10 +92,8 @@ class SendSticker(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent sticker message is returned.
-
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
-
+            :obj:`Message` | ``None``: On success, the sent sticker message is returned, otherwise, in case the upload
+            is deliberately stopped with :meth:`stop_transmission`, None is returned.
         Raises:
             RPCError: In case of a Telegram RPC error.
         """
diff --git a/pyrogram/client/methods/messages/send_video.py b/pyrogram/client/methods/messages/send_video.py
index 92066e19..d2d5afc0 100644
--- a/pyrogram/client/methods/messages/send_video.py
+++ b/pyrogram/client/methods/messages/send_video.py
@@ -124,9 +124,8 @@ class SendVideo(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent video message is returned.
-
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
+            :obj:`Message` | ``None``: On success, the sent video message is returned, otherwise, in case the upload
+            is deliberately stopped with :meth:`stop_transmission`, None is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/messages/send_video_note.py b/pyrogram/client/methods/messages/send_video_note.py
index 8886c588..c17ea92a 100644
--- a/pyrogram/client/methods/messages/send_video_note.py
+++ b/pyrogram/client/methods/messages/send_video_note.py
@@ -107,9 +107,8 @@ class SendVideoNote(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent video note message is returned.
-
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
+            :obj:`Message` | ``None``: On success, the sent video note message is returned, otherwise, in case the
+            pload is deliberately stopped with :meth:`stop_transmission`, None is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/messages/send_voice.py b/pyrogram/client/methods/messages/send_voice.py
index 3631d828..59031f5f 100644
--- a/pyrogram/client/methods/messages/send_voice.py
+++ b/pyrogram/client/methods/messages/send_voice.py
@@ -105,9 +105,8 @@ class SendVoice(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent voice message is returned.
-
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
+            :obj:`Message` | ``None``: On success, the sent voice message is returned, otherwise, in case the upload
+            is deliberately stopped with :meth:`stop_transmission`, None is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/users/get_user_profile_photos_count.py b/pyrogram/client/methods/users/get_user_profile_photos_count.py
index f5526584..7870d003 100644
--- a/pyrogram/client/methods/users/get_user_profile_photos_count.py
+++ b/pyrogram/client/methods/users/get_user_profile_photos_count.py
@@ -33,7 +33,7 @@ class GetUserProfilePhotosCount(BaseClient):
                 For a contact that exists in your Telegram address book you can use his phone number (str).
 
         Returns:
-            ``int``: On success, an integer is returned.
+            ``int``: On success, the user profile photos count is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.
diff --git a/pyrogram/client/methods/users/get_users.py b/pyrogram/client/methods/users/get_users.py
index e95fedc7..4ec0e893 100644
--- a/pyrogram/client/methods/users/get_users.py
+++ b/pyrogram/client/methods/users/get_users.py
@@ -24,6 +24,7 @@ from ...ext import BaseClient
 
 
 class GetUsers(BaseClient):
+    # TODO: Add Users type and use that
     def get_users(
         self,
         user_ids: Union[Iterable[Union[int, str]], int, str]
@@ -38,9 +39,9 @@ class GetUsers(BaseClient):
                 Iterators and Generators are also accepted.
 
         Returns:
-            :obj:`User`: In case *user_ids* was an integer or string.
-
-            List of :obj:`User` -- In case *user_ids* was an iterable, even if the iterable contained one item only.
+            :obj:`User` | List of :obj:`User`: In case *user_ids* was an integer or string the single requested user is
+            returned, otherwise, in case *user_ids* was an iterable a list of users is returned, even if the iterable
+            contained one item only.
 
         Raises:
             RPCError: In case of a Telegram RPC error.