Reword some parts of the docs

delivrance · delivrance · commit 317a64758360 · 2019-06-07T15:50:15.000+02:00
diff --git a/docs/source/topics/advanced-usage.rst b/docs/source/topics/advanced-usage.rst
@@ -103,9 +103,9 @@ sending messages with IDs only thanks to cached access hashes.
 There are three different InputPeer types, one for each kind of Telegram entity.
 Whenever an InputPeer is needed you must pass one of these:
 
-    - :class:`~pyrogram.api.types.InputPeerUser` - Users
-    - :class:`~pyrogram.api.types.InputPeerChat` -  Basic Chats
-    - :class:`~pyrogram.api.types.InputPeerChannel` - Either Channels or Supergroups
+- :class:`~pyrogram.api.types.InputPeerUser` - Users
+- :class:`~pyrogram.api.types.InputPeerChat` -  Basic Chats
+- :class:`~pyrogram.api.types.InputPeerChannel` - Either Channels or Supergroups
 
 But you don't necessarily have to manually instantiate each object because, luckily for you, Pyrogram already provides
 :meth:`~pyrogram.Client.resolve_peer` as a convenience utility method that returns the correct InputPeer
@@ -120,9 +120,9 @@ kind of ID.
 
 For example, given the ID *123456789*, here's how Pyrogram can tell entities apart:
 
-    - ``+ID`` User: *123456789*
-    - ``-ID`` Chat: *-123456789*
-    - ``-100ID`` Channel or Supergroup: *-100123456789*
+- ``+ID`` User: *123456789*
+- ``-ID`` Chat: *-123456789*
+- ``-100ID`` Channel or Supergroup: *-100123456789*
 
 So, every time you take a raw ID, make sure to translate it into the correct ID when you want to use it with an
 high-level method.
diff --git a/docs/source/topics/config-file.rst b/docs/source/topics/config-file.rst
@@ -1,14 +1,14 @@
 Configuration File
 ==================
 
-As already mentioned in previous sections, Pyrogram can be configured by the use of an INI file.
-This page explains how this file is structured in Pyrogram, how to use it and why.
+As already mentioned in previous pages, Pyrogram can be configured by the use of an INI file.
+This page explains how this file is structured, how to use it and why.
 
 Introduction
 ------------
 
 The idea behind using a configuration file is to help keeping your code free of private settings information such as
-the API Key and Proxy without having you to even deal with how to load such settings. The configuration file, usually
+the API Key and Proxy, without having you to even deal with how to load such settings. The configuration file, usually
 referred as ``config.ini`` file, is automatically loaded from the root of your working directory; all you need to do is
 fill in the necessary parts.
 
diff --git a/docs/source/topics/create-filters.rst b/docs/source/topics/create-filters.rst
@@ -13,9 +13,10 @@ Custom Filters
 --------------
 
 An example to demonstrate how custom filters work is to show how to create and use one for the
-:class:`~pyrogram.CallbackQueryHandler`. Note that callback queries updates are only received by bots; create and
-:doc:`authorize your bot <../start/auth>`, then send a message with an inline keyboard to yourself. This allows you to
-test your filter by pressing the inline button:
+:class:`~pyrogram.CallbackQueryHandler`. Note that callback queries updates are only received by bots as result of a
+user pressing an inline button attached to the bot's message; create and :doc:`authorize your bot <../start/auth>`,
+then send a message with an inline keyboard to yourself. This allows you to test your filter by pressing the inline
+button:
 
 .. code-block:: python
 
@@ -25,7 +26,7 @@ test your filter by pressing the inline button:
         "username",  # Change this to your username or id
         "Pyrogram's custom filter test",
         reply_markup=InlineKeyboardMarkup(
-            [[InlineKeyboardButton("Press me", b"pyrogram")]]
+            [[InlineKeyboardButton("Press me", "pyrogram")]]
         )
     )
 
@@ -36,22 +37,22 @@ For this basic filter we will be using only the first two parameters of :meth:`~
 
 The code below creates a simple filter for hardcoded, static callback data. This filter will only allow callback queries
 containing "Pyrogram" as data, that is, the function *func* you pass returns True in case the callback query data
-equals to ``b"Pyrogram"``.
+equals to ``"Pyrogram"``.
 
 .. code-block:: python
 
     static_data = Filters.create(
         name="StaticdData",
-        func=lambda flt, callback_query: callback_query.data == b"Pyrogram"
+        func=lambda flt, query: query.data == "Pyrogram"
     )
 
 The ``lambda`` operator in python is used to create small anonymous functions and is perfect for this example, the same
 could be achieved with a normal function, but we don't really need it as it makes sense only inside the filter's scope:
 
 .. code-block:: python
 
-    def func(flt, callback_query):
-        return callback_query.data == b"Pyrogram"
+    def func(flt, query):
+        return query.data == "Pyrogram"
 
     static_data = Filters.create(
         name="StaticData",
@@ -63,8 +64,8 @@ The filter usage remains the same:
 .. code-block:: python
 
     @app.on_callback_query(static_data)
-    def pyrogram_data(client, callback_query):
-        client.answer_callback_query(callback_query.id, "it works!")
+    def pyrogram_data(_, query):
+        query.answer("it works!")
 
 Filters with Arguments
 ----------------------
@@ -79,14 +80,14 @@ This is how a dynamic custom filter looks like:
     def dynamic_data(data):
         return Filters.create(
             name="DynamicData",
-            func=lambda flt, callback_query: flt.data == callback_query.data,
-            data=data  # "data" kwarg is accessed with "filter.data"
+            func=lambda flt, query: flt.data == query.data,
+            data=data  # "data" kwarg is accessed with "flt.data"
         )
 
 And its usage:
 
 .. code-block:: python
 
-    @app.on_callback_query(dynamic_data(b"Pyrogram"))
-    def pyrogram_data(client, callback_query):
-        client.answer_callback_query(callback_query.id, "it works!")
+    @app.on_callback_query(dynamic_data("Pyrogram"))
+    def pyrogram_data(_, query):
+        query.answer("it works!")
diff --git a/docs/source/topics/more-on-updates.rst b/docs/source/topics/more-on-updates.rst
@@ -29,15 +29,15 @@ For example, take these two handlers:
         print("Just Text")
 
 Here, ``just_text`` is never executed because ``text_or_sticker``, which has been registered first, already handles
-texts (``Filters.text`` is shared and conflicting). To enable it, register the function using a different group:
+texts (``Filters.text`` is shared and conflicting). To enable it, register the handler using a different group:
 
 .. code-block:: python
 
     @app.on_message(Filters.text, group=1)
     def just_text(client, message):
         print("Just Text")
 
-Or, if you want ``just_text`` to be fired *before* ``text_or_sticker`` (note ``-1``, which is less than ``0``):
+Or, if you want ``just_text`` to be executed *before* ``text_or_sticker`` (note ``-1``, which is less than ``0``):
 
 .. code-block:: python
 
diff --git a/docs/source/topics/use-filters.rst b/docs/source/topics/use-filters.rst
@@ -25,7 +25,8 @@ Let's start right away with a simple example:
         def my_handler(client, message):
             print(message)
 
--   or, without decorators. Here filters are passed as the second argument of the handler constructor:
+-   or, without decorators. Here filters are passed as the second argument of the handler constructor; the first is the
+    callback function itself:
 
     .. code-block:: python
         :emphasize-lines: 8
