Update examples

examples/README.md

@@ -1,17 +1,17 @@
 # Examples
 
 This folder contains example scripts to show you how **Pyrogram** looks like.
-You can start with [hello_world.py](https://github.com/pyrogram/pyrogram/blob/master/examples/hello_world.py) and continue
-with the more advanced examples.
+You can start with [hello_world.py](https://github.com/pyrogram/pyrogram/blob/master/examples/hello_world.py)
+and continue with the more advanced examples.
 
 Every script is working right away (provided you correctly set up your credentials), meaning
-you can simply copy-paste and run, the only things you have to change are your session names and the target chats
+you can simply copy-paste and run, the only things you have to change are your session names and the target chats.
 
+- [**hello_world.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/hello_world.py)
 - [**echo_bot.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/echo_bot.py)
+- [**welcome_bot.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/welcome_bot.py)
 - [**get_history.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/get_history.py)
 - [**get_participants.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/get_participants.py)
 - [**get_participants2.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/get_participants2.py)
-- [**hello_world.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/hello_world.py)
 - [**inline_bots.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/inline_bots.py)
 - [**raw_update_handler.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/raw_update_handler.py)
-- [**welcome_bot.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/welcome_bot.py)

examples/echo_bot.py

@@ -1,6 +1,11 @@
 from pyrogram import Client, Filters
 
-"""This simple echo bot replies to every private text message"""
+"""This simple echo bot replies to every private text message.
+
+It uses the @on_message decorator to register a MessageHandler
+and applies two filters on it, Filters.text and Filters.private to make
+sure it will only reply to private text messages.
+"""
 
 app = Client("my_account")
 

examples/get_history.py

@@ -4,6 +4,8 @@ from pyrogram import Client
 from pyrogram.api import functions
 from pyrogram.api.errors import FloodWait
 
+"""This example shows how to retrieve the full message history of a chat"""
+
 app = Client("my_account")
 app.start()
 

examples/get_participants.py

@@ -4,10 +4,15 @@ from pyrogram import Client
 from pyrogram.api import functions, types
 from pyrogram.api.errors import FloodWait
 
+"""This simple GetParticipants method usage shows you how to get the first 10.000 users of a chat.
+
+Refer to get_participants2.py for more than 10.000 users.
+"""
+
 app = Client("my_account")
 app.start()
 
-target = "username"  # Target channel/supergroup
+target = "pyrogramchat"  # Target channel/supergroup
 users = []  # List that will contain all the users of the target chat
 limit = 200  # Amount of users to retrieve for each API call
 offset = 0  # Offset starts at 0

examples/get_participants2.py

@@ -5,8 +5,7 @@ from pyrogram import Client
 from pyrogram.api import functions, types
 from pyrogram.api.errors import FloodWait
 
-"""
-This is an improved version of get_participants.py
+"""This is an improved version of get_participants.py
 
 Since Telegram will return at most 10.000 users for a single query, this script
 repeats the search using numbers ("0" to "9") and all the available ascii letters ("a" to "z").
@@ -18,7 +17,7 @@ as some user names may not contain ascii letters at all.
 app = Client("my_account")
 app.start()
 
-target = "username"  # Target channel/supergroup username or id
+target = "pyrogramchat"  # Target channel/supergroup username or id
 users = {}  # To ensure uniqueness, users will be stored in a dictionary with user_id as key
 limit = 200  # Amount of users to retrieve for each API call (200 is the maximum)
 

examples/hello_world.py

@@ -1,11 +1,11 @@
 from pyrogram import Client
 
-"""This example demonstrates a simple API methods usage"""
+"""This example demonstrates a basic API usage"""
 
-# Create a new Client
+# Create a new Client instance
 app = Client("my_account")
 
-# Start the Client
+# Start the Client before calling any API method
 app.start()
 
 # Send a message to yourself, Markdown is enabled by default
@@ -14,5 +14,5 @@ app.send_message("me", "Hi there! I'm using **Pyrogram**")
 # Send a location to yourself
 app.send_location("me", 51.500729, -0.124583)
 
-# Stop the client
+# Stop the client when you're done
 app.stop()

examples/inline_bots.py

@@ -1,5 +1,7 @@
 from pyrogram import Client
 
+"""This example shows how to query an inline bot"""
+
 # Create a new Client
 app = Client("my_account")
 

examples/welcome_bot.py

@@ -1,7 +1,7 @@
 from pyrogram import Client, Emoji, Filters
 
-"""
-This is the Welcome Bot in @PyrogramChat
+"""This is the Welcome Bot in @PyrogramChat.
+
 It uses the Emoji module to easily add emojis in your text messages and Filters
 to make it only work for specific messages in a specific chat 
 """
@@ -11,16 +11,19 @@ app = Client("my_account")
 
 @app.on_message(Filters.chat("PyrogramChat") & Filters.new_chat_members)
 def welcome(client, message):
+    # Build the new members list (with mentions) by using their first_name
     new_members = ", ".join([
         "[{}](tg://user?id={})".format(i.first_name, i.id)
         for i in message.new_chat_members
     ])
 
+    # Build the welcome message by using an emoji and the list we built above
     text = "{} Welcome to [Pyrogram](https://docs.pyrogram.ml/)'s group chat {}!".format(
         Emoji.SPARKLES,
         new_members
     )
 
+    # Send the welcome message
     client.send_message(
         message.chat.id, text,
         reply_to_message_id=message.message_id,