Fix typo and rewrite tutorial part

Author: joelwurtz

docs/discovery.md

@@ -19,7 +19,7 @@ composer require "php-http/discovery"
 
 ## HTTP Client Discovery
 
-This type of discovery finds a HTTP Client implementation.
+This type of discovery finds an HTTP Client implementation.
 
 ``` php
 use Http\Client\HttpClient;
@@ -33,7 +33,7 @@ class MyClass
     protected $httpClient;
 
     /**
-     * @param HttpClient|null $httpClient to do HTTP requests.
+     * @param HttpClient|null $httpClient Client to do HTTP requests, if not set, autodiscovery will be used to find a HTTP client.
      */
     public function __construct(HttpClient $httpClient = null)
     {
@@ -58,7 +58,7 @@ class MyClass
     protected $httpAsyncClient;
 
     /**
-     * @param HttpAsyncClient|null $httpAsyncClient to do HTTP requests.
+     * @param HttpAsyncClient|null $httpAsyncClient Client to do HTTP requests, if not set, autodiscovery will be used to find an asynchronous client.
      */
     public function __construct(HttpAsyncClient $httpAsyncClient = null)
     {
@@ -69,7 +69,7 @@ class MyClass
 
 ## PSR-7 Message Factory Discovery
 
-This type of discovery finds a [PSR-7](http://www.php-fig.org/psr/psr-7/) Message implementation and their [factories](message-factory.md).
+This type of discovery finds a [message factory](message-factory.md) for a [PSR-7](http://www.php-fig.org/psr/psr-7/) Message implementation.
 
 ``` php
 use Http\Message\MessageFactory;
@@ -95,7 +95,7 @@ class MyClass
 
 ## PSR-7 URI Factory Discovery
 
-This type of discovery finds a [PSR-7](http://www.php-fig.org/psr/psr-7/) URI implementation and their factories.
+This type of discovery finds a uri factory for a [PSR-7](http://www.php-fig.org/psr/psr-7/) URI implementation.
 
 ``` php
 use Http\Message\UriFactory;
@@ -141,7 +141,8 @@ Classes registered manually are put on top of the list.
 
 ### Writing your own discovery
 
-Each discovery service is based on the `ClassDiscovery` and has to specify a `cache` field and a `class` field to specify classes for the corresponding service. The fields need to be redeclared in each discovery class. If `ClassDiscovery` would declare them, they would be shared between the discovery classes which would make no sense.
+Each discovery service is based on the `ClassDiscovery` and has to specify a `cache` property and a `class` property to specify classes for the corresponding service. 
+Since they are static, this properties need to be redeclared in each discovery class. If `ClassDiscovery` would declare them, they would be shared between the discovery classes which would make no sense.
 
 Here is an example discovery:
 

docs/httplug.md

@@ -5,10 +5,10 @@ Httplug is an abstraction for HTTP clients. There are two main use cases:
 1. Usage in a project
 2. Usage in a reusable package
 
-In both cases, the client provides a `sendRequest` method to send a PSR-7 `RequestInterface` and returns a PSR-7 `ResponseInterface`
+In both cases, the `Http\Client\HttpClient` provides a `sendRequest` method to send a PSR-7 `RequestInterface` and returns a PSR-7 `ResponseInterface`
 or throws an exception that implements `Http\Client\Exception`.
 
-There is also the HttpAsyncClient, available in [php-http/httplug-async](https://packagist.org/packages/php-http/httplug-async), which provides the `sendAsyncRequest` method to send a request asynchronously and returns a `Http\Client\Promise`.
+There is also the `Http\Client\HttpAsyncClient`, available in [php-http/httplug-async](https://packagist.org/packages/php-http/httplug-async), which provides the `sendAsyncRequest` method to send a request asynchronously and returns a `Http\Client\Promise`.
 It can be used later to retrieve a PSR-7 `ResponseInterface` or an exception that implements `Http\Client\Exception`.
 
 
@@ -24,20 +24,18 @@ See the [tutorial](tutorial.md) for a concrete example.
 Httplug implementations typically are either HTTP clients of their own, or they are adapters wrapping existing clients like Guzzle 6.
 In the latter case, they will depend on the required client implementation, so you only need to require the adapter and not the actual client.
 
-There is two kind of implementation:
+There are two kind of implementation:
 
- * [php-http/client-implementation](https://packagist.org/providers/php-http/client-implementation), the standard implementation, send requests with a synchronous workflow
- * [php-http/client-async-implementation](https://packagist.org/providers/php-http/client-async-implementation), send requests with an asynchronous workflow by returning promises
+ - [php-http/client-implementation](https://packagist.org/providers/php-http/client-implementation), the synchronous implementation that waits for the response / error before returning from the `sendRequest` method.
+ - [php-http/client-async-implementation](https://packagist.org/providers/php-http/async-client-implementation), the asynchronous implementation that immediately returns a `Http\Client\Promise`, allowing to send several requests in parallel and handling responses later.
 
-See [https://packagist.org/providers/php-http/client-implementation](https://packagist.org/providers/php-http/client-implementation) or [https://packagist.org/providers/php-http/client-async-implementation](https://packagist.org/providers/php-http/client-async-implementation) for
-the full list of implementations.
+Check links above for the full list of implementations.
 
 Note: Until Httplug 1.0 becomes stable, we will focus on the Guzzle6 adapter.
 
 ## Usage in a project
 
-When writing an application, you need to require a concrete [client implementation](https://packagist.org/providers/php-http/client-implementation) or
-a concrete [async client implementation](https://packagist.org/providers/php-http/client-async-implementation).
+When writing an application, you need to require a concrete [implementation](https://packagist.org/providers/php-http/client-implementation).
 
 See [virtual package](virtual-package.md) for more information on the topic of working with Httplug implementations.
 

docs/tutorial.md

@@ -34,7 +34,7 @@ TODO: create client instance with discovery and do some requests
 
 ## Using an asynchronous client
 
-When using an asynchronous client, it will use a PSR-7 `RequestInterface` and returns a `Http\Client\Promise` :
+Asynchronous client accepts a PSR-7 `RequestInterface` and returns a `Http\Client\Promise` :
 
 ```php
 use Http\Discovery\HttpAsyncClientDiscovery;
@@ -43,73 +43,78 @@ $httpAsyncClient = HttpAsyncClientDiscovery::find();
 $promise = $httpAsyncClient->sendAsyncRequest($request);
 ```
 
-This promise allows you to : 
+### Using callback system
 
- * Add callbacks for when the response is available or an errors happens by using the then method:
+This promise allows you to add callbacks for when the response is available or an errors happens by using the then method:
 
- ```php
- $promise->then(function (ResponseInterface $response) {
-     // onFulfilled callback
-     echo 'The response is available';
-    
-     return $response;
- }, function (Exception $e) {
-     // onRejected callback
-     echo 'An error happens';
-    
-     throw $e;    
- });
- ```
+```php
+$promise->then(function (ResponseInterface $response) {
+    // onFulfilled callback
+    echo 'The response is available';
+
+    return $response;
+}, function (Exception $e) {
+    // onRejected callback
+    echo 'An error happens';
+
+    throw $e;    
+});
+```
 
- This method will return another promise so you can manipulate the response and/or exception and
- still provide a way to interact with this object for your users:
+This method will return another promise so you can manipulate the response and/or exception and
+still provide a way to interact with this object for your users:
 
- ```php
- $promise->then(function (ResponseInterface $response) {
-     // onFulfilled callback
-     echo 'The response is available';
+```php
+$promise->then(function (ResponseInterface $response) {
+    // onFulfilled callback
+    echo 'The response is available';
 
-     return $response;
- }, function (Exception $e) {
-     // onRejected callback
-     echo 'An error happens';
+    return $response;
+}, function (Exception $e) {
+    // onRejected callback
+    echo 'An error happens';
 
-     throw $e;    
- })->then(function (ResponseInterface $response) {
-     echo 'Response stil available';
+    throw $e;    
+})->then(function (ResponseInterface $response) {
+    echo 'Response stil available';
 
-     return $response;
- }, function (Exception $e) {
-      throw $e
- });
- ```
+    return $response;
+}, function (Exception $e) {
+     throw $e
+});
+```
 
- In order to achieve the chain callback, if you read previous examples carefully, callbacks provided to the `then` method __must__ 
- return a PSR-7 `ResponseInterface` or throw a `Http\Client\Exception`. For both of the callbacks, if it returns a PSR-7 `ResponseInterface` 
- it will call the `onFulfilled` callback for the next element in the chain, if it throws a `Http\Client\Exception` it will call the `onRejected`
- callback.
+In order to achieve the chain callback, if you read previous examples carefully, callbacks provided to the `then` method __must__ 
+return a PSR-7 `ResponseInterface` or throw a `Http\Client\Exception`. For both of the callbacks, if it returns a PSR-7 `ResponseInterface` 
+it will call the `onFulfilled` callback for the next element in the chain, if it throws a `Http\Client\Exception` it will call the `onRejected`
+callback.
 
- i.e. you can inverse the behavior of a call:
+i.e. you can inverse the behavior of a call:
 
- ```php
-  $promise->then(function (ResponseInterface $response) use($request) {
-      // onFulfilled callback
-      echo 'The response is available, but it\'s not ok...';
-      
-      throw new HttpException('My error message', $request, $response);
-  }, function (Exception $e) {
-      // onRejected callback
-      echo 'An error happens, but it\'s ok...';
+```php
+$promise->then(function (ResponseInterface $response) use($request) {
+    // onFulfilled callback
+    echo 'The response is available, but it\'s not ok...';
 
-      return $exception->getResponse();  
-  });
-  ```
-  
- * Get the state of the promise with `$promise->getState()` will return of one `Promise::PENDING`, `Promise::FULFILLED` or `Promise::REJECTED`
- * Get the response of the promise if it's in `FULFILLED` state with `$promise->getResponse()` call
- * Get the error of the promise if it's in `REJECTED` state with `$promise->getRequest()` call
- * wait for the callback to be fulfilled or rejected with the `$promise->wait()` call. The `wait` will return nothing, it will simply call one the callback
- pass to the `then` method depending on the result of the call. It the promise has already been fulfilled or rejected it will do nothing.
+    throw new HttpException('My error message', $request, $response);
+}, function (Exception $e) {
+    // onRejected callback
+    echo 'An error happens, but it\'s ok...';
+
+    return $exception->getResponse();  
+});
+```
+
+Calling the `wait` method on the promise will wait for the response or exception to be available and invoke callback provided in the `then` method.
+
+### Using the promise directly
+
+If you don't want to use the callback system, you can also get the state of the promise with `$promise->getState()` will return of one `Promise::PENDING`, `Promise::FULFILLED` or `Promise::REJECTED`
+
+Then you can get the response of the promise if it's in `FULFILLED` state with `$promise->getResponse()` call or 
+get the error of the promise if it's in `REJECTED` state with `$promise->getRequest()` call
+
+### Example
 
 Here is a full example of a classic usage when using the `sendAsyncRequest` method: