cleanup exception doc

Author: dbu

components/promise.rst

@@ -74,5 +74,8 @@ executed if the request results in an error::
         }
     );
 
+The ``$exception`` of the failure callback SHOULD implement ``Http\Client\Exception``.
+See :doc:`../httplug/exceptions` for more information on the exception classes you might encounter.
+
 .. _`Promise PSR`: https://groups.google.com/forum/?fromgroups#!topic/php-fig/wzQWpLvNSjs
 .. _Promises/A+: https://promisesaplus.com

httplug/exceptions.rst

@@ -1,20 +1,26 @@
 Exceptions
 ==========
 
-HTTPlug defines one Exception interface: ``Http\Client\Exception``. All HTTP
-client exceptions must implement this interface.
+HTTPlug defines a common interface for all exceptions thrown by HTTPlug implementations.
+Every exception thrown by a HTTP client must implement ``Http\Client\Exception``.
 
 ``HttpClient::sendRequest()`` can throw one of the following exceptions.
 
-================================== ====================== ===================
-Exception                          Thrown when            Methods available
-================================== ====================== ===================
-TransferException                  ???
-└ RequestException                 the request is invalid ``getRequest()``
+================================== ============================= ===================
+Exception                          Thrown when                   Methods available
+================================== ============================= ===================
+TransferException                  something unexpected happened -
+└ RequestException                 the request is invalid        ``getRequest()``
  |nbsp| |nbsp| └ NetworkException  no response received
-                                   due to network issues  ``getRequest()``
- |nbsp| |nbsp| └ HttpException     error response         ``getRequest()``
-                                                          ``getResponse()``
-================================== ====================== ===================
+                                   due to network issues         ``getRequest()``
+ |nbsp| |nbsp| └ HttpException     error response                ``getRequest()``
+                                                                 ``getResponse()``
+================================== ============================= ===================
+
+.. note::
+
+    The ``sendAsyncRequest`` should never throw an exception but always return a
+    :doc:`../components/promise`. The exception classes used in ``Promise::wait`` and the ``then``
+    callback are however the same as explained here.
 
 .. |nbsp| unicode:: U+00A0 .. non-breaking space

httplug/introduction.rst

@@ -18,6 +18,7 @@ HTTPlug defines two HTTP client interfaces that we kept as simple as possible:
 
 * ``HttpAsyncClient`` defines a ``sendAsyncRequest`` method that sends a request
   asynchronously and always returns a ``Http\Client\Promise``.
+  See :doc:`../components/promise` for more information.
 
 Implementations
 ---------------