improve curl client doc

Author: dbu

clients/curl-client.rst

@@ -12,25 +12,24 @@ To install the cURL client, run:
 
     $ composer require php-http/curl-client
 
-Usage
------
-
-The cURL client needs a :ref:`message <message-factory>` and a :ref:`stream <stream-factory>`
-factory in order to to work::
+.. include:: includes/install-message-factory.inc
 
-    use Http\Client\Curl\Client;
+.. include:: includes/install-discovery.inc
 
-    $client = new Client($messageFactory, $streamFactory);
+Usage
+-----
 
-Using `php-http/message <https://packagist.org/packages/php-http/message>`_::
+The cURL client needs a :ref:`message factory <message-factory>` and a
+:ref:`stream factory <stream-factory>` in order to to work. You can either specify the factory
+explicitly::
 
     use Http\Client\Curl\Client;
     use Http\Message\MessageFactory\DiactorosMessageFactory;
     use Http\Message\StreamFactory\DiactorosStreamFactory;
 
     $client = new Client(new DiactorosMessageFactory(), new DiactorosStreamFactory());
 
-Using `php-http/discovery <https://packagist.org/packages/php-http/discovery>`_::
+Or you can use :doc:`../discovery`::
 
     use Http\Client\Curl\Client;
     use Http\Discovery\MessageFactoryDiscovery;
@@ -53,7 +52,8 @@ You can use `cURL options <http://php.net/curl_setopt>`_ to configure Client::
     ];
     $client = new Client(MessageFactoryDiscovery::find(), StreamFactoryDiscovery::find(), $options);
 
-These options cannot be used (will be overwritten by Client):
+The following options can not be changed in the set up. Most of them are to be provided with the
+request instead:
 
     * CURLOPT_CUSTOMREQUEST
     * CURLOPT_FOLLOWLOCATION

discovery.rst

@@ -3,6 +3,7 @@ Discovery
 
 The discovery service is a set of static classes which allows to find and use installed resources.
 This is useful in libraries that want to offer zero-configuration services and rely only on the virtual packages.
+Consumers of such a library need to make sure they install one of the implementations.
 
 Currently available discovery services:
 
@@ -15,13 +16,12 @@ The principle is always the same: you call the static ``find`` method on the dis
 implementation was specified. The discovery service will try to locate a suitable implementation.
 If no implementation is found, an ``Http\Discovery\NotFoundException`` is thrown.
 
-
 Installation
 ------------
 
 .. code-block:: bash
 
-        $ composer require php-http/discovery
+    $ composer require php-http/discovery
 
 HTTP Client Discovery
 ---------------------