Enhance documentation

readthedocs/extra/examples/chats-and-channels.rst

@@ -94,12 +94,13 @@ the hash of said channel or group.
 Retrieving all chat members (channels too)
 ******************************************
 
-You can use
-`client.get_participants <telethon.telegram_client.TelegramClient.get_participants>`
-to retrieve the participants (click it to see the relevant parameters).
-Most of the time you will just need ``client.get_participants(entity)``.
+.. note::
+
+    Use the `telethon.telegram_client.TelegramClient.iter_participants`
+    friendly method instead unless you have a better reason not to!
+
+    This method will handle different chat types for you automatically.
 
-This is what said method is doing behind the scenes as an example.
 
 In order to get all the members from a mega-group or channel, you need
 to use :tl:`GetParticipantsRequest`. As we can see it needs an

readthedocs/extra/examples/projects-using-telethon.rst

@@ -12,6 +12,7 @@ the library.
     `issue 744 <https://github.com/LonamiWebs/Telethon/issues/744>`_
     so it can be included in the next revision of the documentation!
 
+.. _projects-telegram-export:
 
 telegram-export
 ***************
@@ -22,6 +23,7 @@ telegram-export
 A tool to download Telegram data (users, chats, messages, and media)
 into a database (and display the saved data).
 
+.. _projects-mautrix-telegram:
 
 mautrix-telegram
 ****************
@@ -31,6 +33,7 @@ mautrix-telegram
 
 A Matrix-Telegram hybrid puppeting/relaybot bridge.
 
+.. _projects-telegramtui:
 
 TelegramTUI
 ***********

readthedocs/extra/examples/users.rst

@@ -65,6 +65,6 @@ through :tl:`UploadProfilePhoto`:
 
         from telethon.tl.functions.photos import UploadProfilePhotoRequest
 
-        client(functions.photos.UploadProfilePhotoRequest(
+        client(UploadProfilePhotoRequest(
             client.upload_file('/path/to/some/file')
         ))

readthedocs/extra/examples/working-with-messages.rst

@@ -11,11 +11,14 @@ Working with messages
 Forwarding messages
 *******************
 
-This request is available as a friendly method through
-`client.forward_messages <telethon.telegram_client.TelegramClient.forward_messages>`,
-and can be used like shown below:
+.. note::
 
-    .. code-block:: python
+    Use the `telethon.telegram_client.TelegramClient.forward_messages`
+    friendly method instead unless you have a better reason not to!
+
+    This method automatically accepts either a single message or many of them.
+
+.. code-block:: python
 
         # If you only have the message IDs
         client.forward_messages(
@@ -51,6 +54,14 @@ too, if that's all you have.
 Searching Messages
 *******************
 
+.. note::
+
+    Use the `telethon.telegram_client.TelegramClient.iter_messages`
+    friendly method instead unless you have a better reason not to!
+
+    This method has ``search`` and ``filter`` parameters that will
+    suit your needs.
+
 Messages are searched through the obvious :tl:`SearchRequest`, but you may run
 into issues_. A valid example would be:
 
@@ -71,7 +82,8 @@ into issues_. A valid example would be:
             limit=10,       # How many results
             max_id=0,       # Maximum message ID
             min_id=0,       # Minimum message ID
-            from_id=None    # Who must have sent the message (peer)
+            from_id=None,   # Who must have sent the message (peer)
+            hash=0          # Special number to return nothing on no-change
         ))
 
 It's important to note that the optional parameter ``from_id`` could have