Many minor documentation enhancements

docs/source/api/client.rst

@@ -1,7 +1,11 @@
 Pyrogram Client
 ===============
 
-This is the Client class. It exposes high-level methods for an easy access to the API.
+You have entered the API Reference section where you can find detailed information about Pyrogram's API. The main Client
+class, all available methods and types, filters, handlers, decorators and bound-methods detailed descriptions can be
+found starting from this page.
+
+This page is about the Client class, which exposes high-level methods for an easy access to the API.
 
 .. code-block:: python
     :emphasize-lines: 1-3

docs/source/api/decorators.rst

@@ -6,7 +6,7 @@ deserve a dedicated page.
 
 Decorators are able to register callback functions for handling updates in a much easier and cleaner way compared to
 :doc:`Handlers <handlers>`; they do so by instantiating the correct handler and calling
-:meth:`~pyrogram.Client.add_handler`, automatically. All you need to do is adding the decorators on top of your
+:meth:`~pyrogram.Client.add_handler` automatically. All you need to do is adding the decorators on top of your
 functions.
 
 .. code-block:: python

docs/source/api/handlers.rst

@@ -2,10 +2,7 @@ Update Handlers
 ===============
 
 Handlers are used to instruct Pyrogram about which kind of updates you'd like to handle with your callback functions.
-
 For a much more convenient way of registering callback functions have a look at :doc:`Decorators <decorators>` instead.
-In case you decided to manually create a handler, use :class:`~pyrogram.Client.add_handler` to register
-it.
 
 .. code-block:: python
     :emphasize-lines: 1, 10

docs/source/api/methods.rst

@@ -1,7 +1,7 @@
 Available Methods
 =================
 
-All Pyrogram methods listed here are bound to a :class:`~pyrogram.Client` instance.
+This page is about Pyrogram methods. All the methods listed here are bound to a :class:`~pyrogram.Client` instance.
 
 .. code-block:: python
     :emphasize-lines: 6

docs/source/api/types.rst

@@ -1,7 +1,7 @@
 Available Types
 ===============
 
-All Pyrogram types listed here are accessible through the main package directly.
+This page is about Pyrogram types. All types listed here are accessible through the main package directly.
 
 .. code-block:: python
     :emphasize-lines: 1

docs/source/index.rst

@@ -28,8 +28,8 @@ Welcome to Pyrogram
     api/bound-methods
     api/handlers
     api/decorators
-    api/filters
     api/errors
+    api/filters
 
 .. toctree::
     :hidden:

docs/source/start/updates.rst

@@ -45,7 +45,9 @@ arrives:
 
     app.run()
 
-#.  Let's examine these four new pieces. First one: a callback function we defined which accepts two arguments -
+Let's examine these four new pieces.
+
+#.  A callback function we defined which accepts two arguments -
     *(client, message)*. This will be the function that gets executed every time a new message arrives and Pyrogram will
     call that function by passing the client instance and the new message instance as argument.
 
@@ -54,14 +56,14 @@ arrives:
         def my_function(client, message):
             print(message)
 
-#.  Second one: the :class:`~pyrogram.MessageHandler`. This object tells Pyrogram the function we defined above must
+#.  The :class:`~pyrogram.MessageHandler`. This object tells Pyrogram the function we defined above must only handle
-    only handle updates that are in form of a :class:`~pyrogram.Message`:
+    updates that are in form of a :class:`~pyrogram.Message`:
 
     .. code-block:: python
 
         my_handler = MessageHandler(my_function)
 
-#.  Third: the method :meth:`~pyrogram.Client.add_handler`. This method is used to actually register the handler and let
+#.  The method :meth:`~pyrogram.Client.add_handler`. This method is used to actually register the handler and let
     Pyrogram know it needs to be taken into consideration when new updates arrive and the internal dispatching phase
     begins.
 
@@ -69,7 +71,7 @@ arrives:
 
         app.add_handler(my_handler)
 
-#.  Last one, the :meth:`~pyrogram.Client.run` method. What this does is simply call :meth:`~pyrogram.Client.start` and
+#.  The :meth:`~pyrogram.Client.run` method. What this does is simply call :meth:`~pyrogram.Client.start` and
     a special method :meth:`~pyrogram.Client.idle` that keeps your main scripts alive until you press ``CTRL+C``; the
     client will be automatically stopped after that.
 

docs/source/topics/storage-engines.rst

@@ -95,5 +95,5 @@ engine to properly work as intended.
 
 But, why is the session string so long? Can't it be shorter? No, it can't. The session string already packs the bare
 minimum data Pyrogram needs to successfully reconnect to an authorized session, and the 2048-bits auth key is the major
-contributor to the overall length. Needless to repeat that this string, as well as any other session storage, represent
+contributor to the overall length. Needless to say that this string, as well as any other session storage, represent
 strictly personal data. Keep them safe.

docs/source/topics/use-filters.rst

@@ -1,8 +1,8 @@
 Using Filters
 =============
 
-So far we've seen how to register a callback function that executes every time a specific update comes from the server,
+So far we've seen :doc:`how to register a callback function <../start/updates>` that executes every time a specific update
-but there's much more than that to come.
+comes from the server, but there's much more than that to come.
 
 Here we'll discuss about :class:`~pyrogram.Filters`. Filters enable a fine-grain control over what kind of
 updates are allowed or not to be passed in your callback functions, based on their inner details.