Merge pull request #160 from php-http/doc-style-cleanup

dbu · web-flow · commit 9059cb7419fa · 2016-10-19T14:09:03.000+02:00
cleanup documentation pages
diff --git a/clients/buzz-adapter.rst b/clients/buzz-adapter.rst
@@ -54,7 +54,7 @@ Or if you installed the :doc:`discovery </discovery>` layer::
 
     The message factory parameter is mandatory if the discovery layer is not installed.
 
-Be aware
+Be Aware
 --------
 
 This adapter violates the Liskov substitution principle in a rare edge case. When the adapter is configured to use
diff --git a/clients/curl-client.rst b/clients/curl-client.rst
@@ -37,7 +37,7 @@ Or you can use :doc:`../discovery`::
 
     $client = new Client(MessageFactoryDiscovery::find(), StreamFactoryDiscovery::find());
 
-Configuring client
+Configuring Client
 ------------------
 
 You can use `cURL options <http://php.net/curl_setopt>`_ to configure Client::
diff --git a/clients/mock-client.rst b/clients/mock-client.rst
@@ -14,7 +14,7 @@ To install the Mock client, run:
 
     $ composer require php-http/mock-client
 
-Collect requests
+Collect Requests
 ----------------
 
 To make assertions::
@@ -40,7 +40,7 @@ To make assertions::
         }
     }
 
-Fake responses and exceptions
+Fake Responses and Exceptions
 -----------------------------
 
 Test how your code behaves when the HTTP client throws exceptions or returns
diff --git a/components/multipart-stream-builder.rst b/components/multipart-stream-builder.rst
@@ -34,7 +34,7 @@ A multipart stream is a special kind of stream that is used to transfer files ov
 
 In the request above you see a set of HTTP headers and a body with two streams. The body starts and ends with a "boundary" and it is also this boundary that separates the streams. That boundary also needs to be specified in the ``Content-Type`` header.
 
-Building a multipart stream
+Building a Multipart Stream
 ```````````````````````````
 
 To build a multipart stream you may use the ``MultipartStreamBuilder``. It is not coupled to any stream implementation so it needs a ``StreamFactory`` to create the streams.
diff --git a/development/contributing.rst b/development/contributing.rst
@@ -3,7 +3,7 @@ Contributing
 
 If you're here, you would like to contribute to this project and you're really welcome!
 
-Bug reports
+Bug Reports
 -----------
 
 If you find a bug or a documentation issue, please report it or even better: fix it :). If you report it,
@@ -14,15 +14,15 @@ please be as precise as possible. Here is a little list of required information:
  - Backtrace which might help identifying the bug
 
 
-Security issues
+Security Issues
 ---------------
 
 If you discover any security related issues,
 please contact us at security@php-http.org instead of submitting an issue on GitHub.
 This allows us to fix the issue and release a security hotfix without publicly disclosing the vulnerability.
 
 
-Feature requests
+Feature Requests
 ----------------
 
 If you think a feature is missing, please report it or even better: implement it :). If you report it, describe the more
@@ -86,7 +86,7 @@ If your branch conflicts with the master branch, you will need to rebase and re-
     $ git pull --rebase upstream master
     $ git push -f origin feature-or-bug-fix-description
 
-Coding standard
+Coding Standard
 ---------------
 
 This repository follows the `PSR-2 standard`_ and so, if you want to contribute,
diff --git a/development/documentation.rst b/development/documentation.rst
@@ -8,7 +8,7 @@ Install Sphinx
 --------------
 
 
-Install on local machine
+Install on Local Machine
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 The installation for Sphinx differs between system. See `Sphinx installation page`_ for details. When Sphinx is
@@ -42,7 +42,7 @@ without entering the container shell:
     on the host too.
 
 
-Build documentation
+Build Documentation
 -------------------
 
 Before we can build the documentation we have to make sure to install all requirements.
diff --git a/httplug/introduction.rst b/httplug/introduction.rst
@@ -7,8 +7,8 @@ When all packages used in an application only specify HTTPlug,
 the application developers can choose the client that best fits their project
 and use the same client with all packages.
 
-The client interfaces
----------------------
+Client Interfaces
+-----------------
 
 HTTPlug defines two HTTP client interfaces that we kept as simple as possible:
 
diff --git a/httplug/library-developers.rst b/httplug/library-developers.rst
@@ -1,4 +1,4 @@
-HTTPlug for library developers
+HTTPlug for Library Developers
 ==============================
 
 If you’re developing a library or framework that performs HTTP requests, you
@@ -7,7 +7,7 @@ Instead, you should only make sure that *some* HTTP client is available. It is
 then up to your users to decide which HTTP client they want to include in their
 projects. This complies with the `dependency inversion principle`_.
 
-Manage dependencies
+Manage Dependencies
 -------------------
 
 To depend on *some* HTTP client, specify either
@@ -78,14 +78,14 @@ If your library relies on specific plugins, the recommended way is to provide a
 your users, so they can create the correct client from a base HttpClient. See
 :ref:`plugin-client.libraries` for a concrete example.
 
-User documentation
+User Documentation
 ------------------
 
 To explain to your users that they need to install a concrete HTTP client,
 you can point them to :doc:`users`.
 
 
-Your final ``composer.json``
+Your Final ``composer.json``
 ----------------------------
 
 Putting it all together your final ``composer.json`` is much likely to look similar to this:
diff --git a/httplug/tutorial.rst b/httplug/tutorial.rst
@@ -1,4 +1,4 @@
-HTTPlug tutorial
+HTTPlug Tutorial
 ================
 
 This tutorial should give you an idea how to use HTTPlug in your project. HTTPlug has two main use cases:
@@ -17,7 +17,7 @@ We use Composer_ for dependency management. Install it if you don't have it yet.
     there is an integration available. Framework integrations will simplify the way
     you set up clients, letting you focus on handling the requests.
 
-Setting up the project
+Setting up the Project
 ----------------------
 
 .. code-block:: bash
@@ -32,7 +32,7 @@ The last command will install Guzzle as well as the Guzzle HTTPlug adapter and t
 We are now ready to start coding.
 
 
-Writing some simple code
+Writing Some Simple Code
 ------------------------
 
 Create a file ``demo.php`` in the root folder and write the following code::
@@ -43,7 +43,7 @@ Create a file ``demo.php`` in the root folder and write the following code::
     TODO: create client instance with discovery and do some requests
 
 
-Using an asynchronous client
+Using an Asynchronous Client
 ----------------------------
 
 Asynchronous client accepts a PSR-7 ``RequestInterface`` and returns a ``Http\Promise\Promise``::
@@ -53,10 +53,10 @@ Asynchronous client accepts a PSR-7 ``RequestInterface`` and returns a ``Http\Pr
     $httpAsyncClient = HttpAsyncClientDiscovery::find();
     $promise = $httpAsyncClient->sendAsyncRequest($request);
 
-Using callback system
-^^^^^^^^^^^^^^^^^^^^^
+Using the Callback System
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This promise allows you to add callbacks for when the response is available or an errors happens by using the then method::
+The promise allows you to add callbacks for when the response is available or an errors happens by using the then method::
 
     $promise->then(function (ResponseInterface $response) {
         // onFulfilled callback
@@ -161,7 +161,7 @@ Here is a full example of a classic usage when using the ``sendAsyncRequest`` me
     // Do your stuff with the response
     ...
 
-Handling errors
+Handling Errors
 ---------------
 
 TODO: explain how to handle exceptions, distinction between network exception and HttpException.
diff --git a/httplug/usage.rst b/httplug/usage.rst
@@ -6,7 +6,7 @@ HTTPlug is relevant for three groups of users:
 .. toctree::
    :maxdepth: 1
 
-   Library users <users>
-   Application developers <tutorial>
-   Library developers <library-developers>
+   Library Users <users>
+   Application Developers <tutorial>
+   Library Developers <library-developers>
 
diff --git a/httplug/users.rst b/httplug/users.rst
@@ -71,7 +71,7 @@ HTTP client in your project, Composer will throw an error:
 
 You can solve this by including a HTTP client or adapter, as described above.
 
-No  message factories
+No  Message Factories
 `````````````````````
 
 You may get an exception telling you that "No message factories found", this
diff --git a/integrations/symfony-bundle.rst b/integrations/symfony-bundle.rst
@@ -223,7 +223,7 @@ You can configure a client with authentication. Valid authentication types are `
                 factory: 'httplug.factory.guzzle6'
                 plugins: ['httplug.plugin.authentication.my_wsse']
 
-Special HTTP clients
+Special HTTP Clients
 ````````````````````
 
 If you want to use the ``FlexibleHttpClient`` or ``HttpMethodsClient`` from the ``php-http/message`` package you may specify that on the client configuration.
diff --git a/message/authentication.rst b/message/authentication.rst
@@ -14,7 +14,7 @@ Installation
 
     $ composer require php-http/message
 
-Authentication methods
+Authentication Methods
 ^^^^^^^^^^^^^^^^^^^^^^
 
 +----------------+---------------------------------------------------+-----------------------------------------------------+
@@ -149,7 +149,7 @@ The first argument is an authentication method, the second is a regular expressi
     $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::
diff --git a/plugins/build-your-own.rst b/plugins/build-your-own.rst
@@ -96,13 +96,16 @@ To better understand the whole process check existing implementations in the
 Contributing Your Plugins to PHP-HTTP
 -------------------------------------
 
-We are open to contributions. If the plugin is of general interest, is not too complex and does not have dependencies, the best
-is to do a Pull Request to ``php-http/client-common``. Please see the :doc:`contribution guide <../development/contributing>`.
-We don't promise that every plugin gets merged into the core. We need to keep the core as small as
-possible with only the most widely used plugins to keep it maintainable.
-
-The alternative is providing your plugins in your own repository. Please let us know when you do,
-we would like to add a list of existing third party plugins to the list of plugins.
+We are open to contributions. If the plugin is of general interest, not too
+complex and does not have dependencies, the best is to do a Pull Request to
+``php-http/client-common``. Please see the :doc:`contribution guide <../development/contributing>`.
+We don't promise that every plugin gets merged into the core. We need to keep
+the core as small as possible with only the most widely used plugins to keep
+it maintainable.
+
+The alternative is providing your plugins in your own repository. Please let us
+know when you do, we would like to add a list of existing third party plugins
+to the list of plugins.
 
 .. _PSR: https://groups.google.com/forum/?fromgroups#!topic/php-fig/wzQWpLvNSjs
 .. _client-common package: https://github.com/php-http/client-common
diff --git a/plugins/headers.rst b/plugins/headers.rst
@@ -1,16 +1,15 @@
 Header Plugins
 ==============
 
-Header plugins are useful to manage request headers. Many operations are possible:
+Header plugins are useful to manage request headers. Many operations are
+possible with the provided plugins.
 
-Default headers values
+Default Headers Values
 ----------------------
 
-The plugin ``HeaderDefaultsPlugin`` allows you to set default values for given headers.
-That means if a header is not set, it will be added.
-However, if the header is already present, the request is left unchanged.
-
-.. code:: php
+The plugin ``HeaderDefaultsPlugin`` allows you to define default values for
+given headers. If a header is not set, it will be added. However, if the header
+is already present, the request is left unchanged::
 
     use Http\Discovery\HttpClientDiscovery;
     use Http\Client\Common\PluginClient;
@@ -27,11 +26,12 @@ However, if the header is already present, the request is left unchanged.
         [$headerDefaultsPlugin]
     );
 
-Mandatory headers values
+Mandatory Headers Values
 ------------------------
 
-The plugin ``HeaderSetPlugin`` allows you to fix values of given headers. That means that any request passing through
-this plugin will have the given value for the given header.
+The plugin ``HeaderSetPlugin`` allows you to fix values of given headers. That
+means that any request passing through this plugin will be set to the specified
+value. Existing values of the header will be overwritten.
 
 .. code:: php
 
@@ -51,21 +51,17 @@ this plugin will have the given value for the given header.
         [$headerSetPlugin]
     );
 
-
-
-Removing headers
+Removing Headers
 ----------------
 
-The plugin ``HeaderRemovePlugin`` allows you to remove given headers from the request.
+The plugin ``HeaderRemovePlugin`` allows you to remove headers from the request.
 
 .. code:: php
 
     use Http\Discovery\HttpClientDiscovery;
     use Http\Client\Common\PluginClient;
     use Http\Client\Common\Plugin\HeaderRemovePlugin;
 
-    $userAgent = 'Mozilla/5.0 (Windows NT 6.1; WOW64; rv:40.0) Gecko/20100101 Firefox/40.1';
-
     $headerRemovePlugin = new HeaderRemovePlugin([
         'User-Agent'
     ]);
@@ -75,17 +71,17 @@ The plugin ``HeaderRemovePlugin`` allows you to remove given headers from the re
         [$headerRemovePlugin]
     );
 
-
-Appending header values
+Appending Header Values
 -----------------------
 
-The plugin ``HeaderAppendPlugin`` allows you to set headers or to add values to existing headers.
-That means if the request already has the given headers then the value will be appended to the current value
-but if the request does not already have the given header, it will be added to the request with the given value.
+The plugin ``HeaderAppendPlugin`` allows you to add headers. The header will be
+created if not existing yet. If the header already exists, the value will be
+appended to the list of values for this header.
 
 .. note::
 
-    This plugin is very specific and is mostly useful for headers like "forwarded"
+    The use cases for this plugin are limited. One real world example of
+    headers that can have multiple values is "Forwarded".
 
 .. code:: php
 
@@ -104,7 +100,6 @@ but if the request does not already have the given header, it will be added to t
         [$headerAppendPlugin]
     );
 
-
 Mixing operations
 -----------------
 
diff --git a/plugins/introduction.rst b/plugins/introduction.rst
diff --git a/plugins/retry.rst b/plugins/retry.rst

Original file line number	Diff line number	Diff line change
`@@ -14,7 +14,7 @@ To install the Mock client, run:`
`14`	`14`
`15`	`15`	`$ composer require php-http/mock-client`
`16`	`16`
`17`		`-Collect requests`
	`17`	`+Collect Requests`
`18`	`18`	`----------------`
`19`	`19`
`20`	`20`	`To make assertions::`
`@@ -40,7 +40,7 @@ To make assertions::`
`40`	`40`	`}`
`41`	`41`	`}`
`42`	`42`
`43`		`-Fake responses and exceptions`
	`43`	`+Fake Responses and Exceptions`
`44`	`44`	`-----------------------------`
`45`	`45`
`46`	`46`	`Test how your code behaves when the HTTP client throws exceptions or returns`