php-http · sagikazarmark · Dec 28, 2015 · dbu · Jan 2, 2016 · sagikazarmark
diff --git a/docs/components/discovery.md → docs/discovery.md b/docs/components/discovery.md → docs/discovery.md
diff --git a/docs/httplug/index.md → docs/httplug.md b/docs/httplug/index.md → docs/httplug.md
@@ -9,20 +9,18 @@ In both cases, the `Http\Client\HttpClient` provides a `sendRequest` method to s
 and returns a PSR-7 `ResponseInterface`or throws an exception that implements `Http\Client\Exception`.
 
 There is also the `Http\Client\HttpAsyncClient` which provides the `sendAsyncRequest` method to send
-a request asynchronously and returns a `Http\Client\Promise`.
+a request asynchronously and returns a `Http\Promise\Promise`.
 
 The promise allows to specify handlers for a PSR-7 `ResponseInterface`
 or an exception that implements `Http\Client\Exception`.
 
-
-<p class="text-warning">
-    Contract for the `Http\Client\Promise` is temporary until
+!!! warning "Warning:"
+    Contract for the `Http\Promise\Promise` is temporary until
     [PSR is released](https://groups.google.com/forum/?fromgroups#!topic/php-fig/wzQWpLvNSjs).
     Once it is out, we will use this PSR in the main client and deprecate the old contract.
-</p>
 
 
-See the [tutorial](tutorial.md) for a concrete example.
+See the [tutorial](httplug/tutorial.md) for a concrete example.
 
 
 ## HTTPlug implementations
@@ -37,7 +35,7 @@ There are two kind of implementations:
  - [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/async-client-implementation](https://packagist.org/providers/php-http/async-client-implementation):
- the asynchronous implementation that immediately returns a `Http\Client\Promise`,
+ the asynchronous implementation that immediately returns a `Http\Promise\Promise`,
  allowing to send several requests in parallel and handling responses later.
 
 Check links above for the full list of implementations.
@@ -48,7 +46,7 @@ Check links above for the full list of implementations.
 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.
+See [virtual package](httplug/virtual-package.md) for more information on the topic of working with HTTPlug implementations.
 
 
 ## Installation in a reusable package
@@ -84,10 +82,10 @@ You should however always accept injecting the client instance to allow the user
 You can find an example in the [Discovery Component](/components/discovery) documentation.
 
 Users of your package will have to select a concrete adapter in their project to make your package installable.
-Best point them to the [virtual package](virtual-package.md) howto page.
+Best point them to the [virtual package](httplug/virtual-package.md) howto page.
 
 To be able to send requests, you should not depend on a specific PSR-7 implementation,
-but use the [Message Factory Component](/components/message-factory) system.
+but use the [Message Factory Component](message-factory.md) system.
 
 
 ### Framework Integration
@@ -108,4 +106,4 @@ which in most cases affected every adapter as well).
 
 In 2015, a decision has been made to move the library to it's own organization, so PHP HTTP was born.
 
-See [migrating](migrating.md) for a guide how to migrate your code from the Ivory adapter to HTTPlug.
+See [migrating](httplug/migrating.md) for a guide how to migrate your code from the Ivory adapter to HTTPlug.
diff --git a/docs/components/message-factory.md → docs/message-factory.md b/docs/components/message-factory.md → docs/message-factory.md
diff --git a/docs/components/authentication.md → docs/message.md b/docs/components/authentication.md → docs/message.md
@@ -1,9 +1,12 @@
-# Authentication
+# Message
 
-The Authentication component allows you to to implement authentication methods which can simply update the request
-with authentication detail (for example by adding an `Authorization` header).
-This is useful when you have to send multiple requests to the same endpoint. Using an authentication implementation,
-these details can be separated from the actual requests.
+This package contains various HTTP Message related tools:
+
+- Authentication
+- Stream encoding
+- Message decorators
+- [Message factory](/message-factory) for Guzzle PSR-7 and Diactoros
+- Cookie
 
 
 ## Installation
@@ -12,8 +15,15 @@ these details can be separated from the actual requests.
 $ composer require php-http/message
 ```
 
+## Authentication
+
+The Authentication component allows you to to implement authentication methods which can simply update the request
+with authentication detail (for example by adding an `Authorization` header).
+This is useful when you have to send multiple requests to the same endpoint. Using an authentication implementation,
+these details can be separated from the actual requests.
+
 
-## Authentication methods
+### Authentication methods
 
 Method           | Parameters                                        | Behavior
 ---------------- | ------------------------------------------------- | --------
@@ -28,15 +38,15 @@ Matching         | An authentication instance and a matcher callback | Behavior
 [2]: http://www.xml.com/pub/a/2003/12/17/dive.html
 
 
-## Integration with HTTPlug
+### Integration with HTTPlug
 
 Normally requests must be authenticated "by hand" which is not really convenient.
 
 If you use HTTPlug, you can integrate this component into the client using the
 [authentication plugin](/httplug/plugins/authentication).
 
 
-## Examples
+### Examples
 
 General usage looks like the following:
 
@@ -48,7 +58,7 @@ $authentication->authenticate($request);
 ```
 
 
-### Basic Auth
+#### Basic Auth
 
 ``` php
 use Http\Message\Authentication\BasicAuth;
@@ -57,7 +67,7 @@ $authentication = new BasicAuth('username', 'password');
 ```
 
 
-### Bearer
+#### Bearer
 
 ``` php
 use Http\Message\Authentication\Bearer;
@@ -66,7 +76,7 @@ $authentication = new Bearer('token');
 ```
 
 
-### WSSE
+#### WSSE
 
 ``` php
 use Http\Message\Authentication\Wsse;
@@ -75,7 +85,7 @@ $authentication = new Wsse('username', 'password');
 ```
 
 
-### Query Params
+#### Query Params
 
 `http://api.example.com/endpoint?access_token=9zh987g86fg87gh978hg9g79`
 
@@ -94,7 +104,7 @@ $authentication = new QueryParams([
 
 
 
-### Chain
+#### Chain
 
 The idea behind this authentication method is that in some cases you might need to
 authenticate the request with multiple methods.
@@ -115,7 +125,7 @@ $authentication = new Chain($authenticationChain);
 ```
 
 
-### Matching
+#### Matching
 
 With this authentication method you can conditionally add authentication details to your request by passing a callable
 to it. When a request is passed, the callable is called and used as a boolean value in order to decide whether
@@ -152,7 +162,7 @@ $authentication = Matching::createUrlMatcher(new AuthenticationMethod(), '\/api'
 ```
 
 
-## Implement your own
+### Implement your own
 
 Implementing an authentication method is easy: only one method needs to be implemented.