Several documentation fixes and additions

readthedocs/extra/advanced-usage/accessing-the-full-api.rst

@@ -137,4 +137,4 @@ This can further be simplified to:
 
 __ https://lonamiwebs.github.io/Telethon
 __ https://lonamiwebs.github.io/Telethon/methods/index.html
-__ https://lonamiwebs.github.io/Telethon/?q=message
+__ https://lonamiwebs.github.io/Telethon/?q=message&redirect=no

readthedocs/extra/basic/entities.rst

@@ -26,6 +26,12 @@ in response to certain methods, such as :tl:`GetUsersRequest`.
     If the peer is someone in a group, you would similarly
     `client.get_participants(group) <telethon.telegram_client.TelegramClient.get_participants>`.
 
+    Once you have encountered an ID, the library will (by default) have saved
+    their ``access_hash`` for you, which is needed to invoke most methods.
+    This is why sometimes you might encounter this error when working with
+    the library. You should ``except ValueError`` and run code that you know
+    should work to find the entity.
+
 
 Getting entities
 ****************
@@ -125,3 +131,21 @@ library, the raw requests you make to the API are also able to call
 The library will call the ``.resolve()`` method of the request, which will
 resolve ``'username'`` with the appropriated :tl:`InputPeer`. Don't worry if
 you don't get this yet, but remember some of the details here are important.
+
+
+Full entities
+*************
+
+In addition to :tl:`PeerUser`, :tl:`InputPeerUser`, :tl:`User` (and its
+variants for chats and channels), there is also the concept of :tl:`UserFull`.
+
+This full variant has additional information such as whether the user is
+blocked, its notification settings, the bio or about of the user, etc.
+
+There is also :tl:`messages.ChatFull` which is the equivalent of full entities
+for chats and channels, with also the about section of the channel. Note that
+the ``users`` field only contains bots for the channel (so that clients can
+suggest commands to use).
+
+You can get both of these by invoking :tl:`GetFullUser`, :tl:`GetFullChat`
+and :tl:`GetFullChannel` respectively.

readthedocs/telethon.events.rst

@@ -3,12 +3,6 @@
 telethon\.events package
 ========================
 
-.. automodule:: telethon.events
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-
 Every event (builder) subclasses `telethon.events.common.EventBuilder`,
 so all the methods in it can be used from any event builder/event instance.
 
@@ -18,8 +12,6 @@ so all the methods in it can be used from any event builder/event instance.
     :show-inheritance:
 
 
-Below all the event types are listed:
-
 .. automodule:: telethon.events.newmessage
     :members:
     :undoc-members:
@@ -54,3 +46,9 @@ Below all the event types are listed:
     :members:
     :undoc-members:
     :show-inheritance:
+
+.. automodule:: telethon.events
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

telethon/telegram_client.py

@@ -727,6 +727,10 @@ class TelegramClient(TelegramBareClient):
         ``[mention](tg://user?id=123456789)``) and ``pre`` blocks with three
         backticks.
 
+        Sending a ``/start`` command with a parameter (like ``?start=data``)
+        is also done through this method. Simply send ``'/start data'`` to
+        the bot.
+
         Args:
             entity (`entity`):
                 To who will it be sent.
@@ -1119,6 +1123,9 @@ class TelegramClient(TelegramBareClient):
         Sends a "read acknowledge" (i.e., notifying the given peer that we've
         read their messages, also known as the "double check").
 
+        This effectively marks a message as read (or more than one) in the
+        given conversation.
+
         Args:
             entity (`entity`):
                 The chat where these messages are located.
@@ -1868,6 +1875,10 @@ class TelegramClient(TelegramBareClient):
         """
         Downloads the given media, or the media from a specified Message.
 
+        Note that if the download is too slow, you should consider installing
+        ``cryptg`` (through ``pip install cryptg``) so that decrypting the
+        received data is done in C instead of Python (much faster).
+
         message (:tl:`Message` | :tl:`Media`):
             The media or message containing the media that will be downloaded.
 
@@ -2489,10 +2500,9 @@ class TelegramClient(TelegramBareClient):
             return utils.get_input_peer(peer)
 
         raise ValueError(
-            'Could not find the input entity corresponding to "{}". '
-            'Make sure you have encountered this user/chat/channel before. '
-            'If the peer is in your dialogs call client.get_dialogs().'
-            'If the peer belongs to a chat call client.get_participants().'
+            'Could not find the input entity for "{}". Please read https://'
+            'telethon.readthedocs.io/en/latest/extra/basic/entities.html to'
+            'find out more details.'
             .format(peer)
         )