Clarify some aspects of the documentation

telethon/tl/custom/chatgetter.py

@@ -23,7 +23,12 @@ class ChatGetter(abc.ABC):
         Returns the :tl:`User`, :tl:`Chat` or :tl:`Channel` where this object
         belongs to. It may be ``None`` if Telegram didn't send the chat.
 
-        If you're using `telethon.events`, use `get_chat` instead.
+        If you only need the ID, use `chat_id` instead.
+
+        If you need to call a method which needs
+        this chat, use `input_chat` instead.
+
+        If you're using `telethon.events`, use `get_chat()` instead.
         """
         return self._chat
 
@@ -31,6 +36,11 @@ class ChatGetter(abc.ABC):
         """
         Returns `chat`, but will make an API call to find the
         chat unless it's already cached.
+
+        If you only need the ID, use `chat_id` instead.
+
+        If you need to call a method which needs
+        this chat, use `get_input_chat()` instead.
         """
         # See `get_sender` for information about 'min'.
         if (self._chat is None or getattr(self._chat, 'min', None))\
@@ -46,8 +56,10 @@ class ChatGetter(abc.ABC):
     def input_chat(self):
         """
         This :tl:`InputPeer` is the input version of the chat where the
-        message was sent. Similarly to `input_sender`, this doesn't have
-        things like username or similar, but still useful in some cases.
+        message was sent. Similarly to `input_sender
+        <telethon.tl.custom.sendergetter.SenderGetter.input_sender>`, this
+        doesn't have things like username or similar, but still useful in
+        some cases.
 
         Note that this might not be available if the library doesn't
         have enough information available.
@@ -83,11 +95,14 @@ class ChatGetter(abc.ABC):
     def chat_id(self):
         """
         Returns the marked chat integer ID. Note that this value **will
-        be different** from `to_id` for incoming private messages, since
+        be different** from ``to_id`` for incoming private messages, since
         the chat *to* which the messages go is to your own person, but
         the *chat* itself is with the one who sent the message.
 
         TL;DR; this gets the ID that you expect.
+
+        If there is a chat in the object, `chat_id` will *always* be set,
+        which is why you should use it instead of `chat.id <chat>`.
         """
         return utils.get_peer_id(self._chat_peer) if self._chat_peer else None
 

telethon/tl/custom/dialog.py

@@ -55,7 +55,7 @@ class Dialog:
             How many mentions are currently unread in this dialog. Note that
             this value won't update when new messages arrive.
 
-        draft (`telethon.tl.custom.draft.Draft`):
+        draft (`Draft <telethon.tl.custom.draft.Draft>`):
             The draft object in this dialog. It will not be ``None``,
             so you can call ``draft.set_message(...)``.
 

telethon/tl/custom/message.py

@@ -781,7 +781,8 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC):
             filter (`callable`):
                 Clicks the first button for which the callable
                 returns ``True``. The callable should accept a single
-                `telethon.tl.custom.messagebutton.MessageButton` argument.
+                `MessageButton <telethon.tl.custom.messagebutton.MessageButton>`
+                argument.
 
             data (`bytes`):
                 This argument overrides the rest and will not search any

telethon/tl/custom/messagebutton.py

@@ -64,7 +64,7 @@ class MessageButton:
         Emulates the behaviour of clicking this button.
 
         If it's a normal :tl:`KeyboardButton` with text, a message will be
-        sent, and the sent `telethon.tl.custom.message.Message` returned.
+        sent, and the sent `Message <telethon.tl.custom.message.Message>` returned.
 
         If it's an inline :tl:`KeyboardButtonCallback` with text and data,
         it will be "clicked" and the :tl:`BotCallbackAnswer` returned.

telethon/tl/custom/sendergetter.py

@@ -19,7 +19,12 @@ class SenderGetter(abc.ABC):
         Returns the :tl:`User` or :tl:`Channel` that sent this object.
         It may be ``None`` if Telegram didn't send the sender.
 
-        If you're using `telethon.events`, use `get_sender` instead.
+        If you only need the ID, use `sender_id` instead.
+
+        If you need to call a method which needs
+        this chat, use `input_sender` instead.
+
+        If you're using `telethon.events`, use `get_sender()` instead.
         """
         return self._sender
 
@@ -27,6 +32,11 @@ class SenderGetter(abc.ABC):
         """
         Returns `sender`, but will make an API call to find the
         sender unless it's already cached.
+
+        If you only need the ID, use `sender_id` instead.
+
+        If you need to call a method which needs
+        this sender, use `get_input_sender()` instead.
         """
         # ``sender.min`` is present both in :tl:`User` and :tl:`Channel`.
         # It's a flag that will be set if only minimal information is
@@ -47,8 +57,9 @@ class SenderGetter(abc.ABC):
     def input_sender(self):
         """
         This :tl:`InputPeer` is the input version of the user/channel who
-        sent the message. Similarly to `input_chat`, this doesn't have
-        things like username or similar, but still useful in some cases.
+        sent the message. Similarly to `input_chat
+        <telethon.tl.custom.chatgetter.ChatGetter.input_chat>`, this doesn't
+        have things like username or similar, but still useful in some cases.
 
         Note that this might not be available if the library can't
         find the input chat, or if the message a broadcast on a channel.
@@ -74,6 +85,9 @@ class SenderGetter(abc.ABC):
     def sender_id(self):
         """
         Returns the marked sender integer ID, if present.
+
+        If there is a sender in the object, `sender_id` will *always* be set,
+        which is why you should use it instead of `sender.id <sender>`.
         """
         return self._sender_id