Docs revamp. Part 5

docs/source/start/errors.rst

@@ -11,8 +11,9 @@ to control the behaviour of your application. Pyrogram errors all live inside th
 RPCError
 --------
 
-The father of all errors is named ``RPCError``. This error exists in form of a Python exception and is able to catch all
-Telegram API related errors.
+The father of all errors is named ``RPCError``. This error exists in form of a Python exception which is directly
+subclass-ed from Python's main ``Exception`` and is able to catch all Telegram API related errors. This error is raised
+every time a method call against Telegram's API was unsuccessful.
 
 .. code-block:: python
 
@@ -27,7 +28,7 @@ Error Categories
 ----------------
 
 The ``RPCError`` packs together all the possible errors Telegram could raise, but to make things tidier, Pyrogram
-provides categories of errors, which are named after the common HTTP errors:
+provides categories of errors, which are named after the common HTTP errors and subclass-ed from the RPCError:
 
 .. code-block:: python
 
@@ -41,6 +42,32 @@ provides categories of errors, which are named after the common HTTP errors:
 -   `420 - Flood <../api/errors#flood>`_
 -   `500 - InternalServerError <../api/errors#internalservererror>`_
 
+Single Errors
+-------------
+
+For a fine-grained control over every single error, Pyrogram does also expose errors that deal each with a specific
+issue. For example:
+
+.. code-block:: python
+
+    from pyrogram.errors import FloodWait
+
+These errors subclass directly from the category of errors they belong to, which in turn subclass from the father
+RPCError, thus building a class of error hierarchy such as this:
+
+- RPCError
+    - BadRequest
+        - ``MessageEmpty``
+        - ``UsernameOccupied``
+        - ``...``
+    - InternalServerError
+        - ``RpcCallFail``
+        - ``InterDcCallError``
+        - ``...``
+    - ``...``
+
+.. _Errors: api/errors
+
 Unknown Errors
 --------------
 

docs/source/start/invoking.rst

@@ -36,7 +36,7 @@ Now instantiate a new Client object, "my_account" is a session name of your choi
 
     app = Client("my_account")
 
-To actually make use of any method, the client has to be started:
+To actually make use of any method, the client has to be started first:
 
 .. code-block:: python
 

docs/source/start/updates.rst

@@ -9,11 +9,11 @@ Defining Updates
 
 First, let's define what are these updates. As hinted already, updates are simply events that happen in your Telegram
 account (incoming messages, new members join, bot button presses, etc...), which are meant to notify you about a new
-specific state that changed. These updates are handled by registering one or more callback functions in your app using
-`Handlers <../api/handlers>`_.
+specific state that has changed. These updates are handled by registering one or more callback functions in your app
+using `Handlers <../api/handlers>`_.
 
 Each handler deals with a specific event and once a matching update arrives from Telegram, your registered callback
-function will be called and its body executed.
+function will be called back by the framework and its body executed.
 
 Registering an Handler
 ----------------------
@@ -63,8 +63,8 @@ above must only handle updates that are in form of a :obj:`Message <pyrogram.Mes
     my_handler = MessageHandler(my_function)
 
 Third: the method :meth:`add_handler() <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 dispatching phase
-begins.
+handler and let Pyrogram know it needs to be taken into consideration when new updates arrive and the internal
+dispatching phase begins.
 
 .. code-block:: python
 
@@ -109,4 +109,4 @@ to do so is by decorating your callback function with the :meth:`on_message() <p
     ``my_function[0].callback``, that is, the *callback* field of the *handler* object which is the first element in the
     tuple, accessed by bracket notation *[0]*.
 
-.. _API methods: usage.html
+.. _API methods: invoking