Provides edits for PSR-18 (php-fig#1060)

This patch reviews primarily the language of the specification, updating
it with the following:

- Consistent usage of RFC 2119 verbiage.
- Code marks around all words representing code, HTTP artifacts, etc.
- Minor rephrasing to remove ambiguity, passive phrasing, etc.

proposed/http-client/http-client-meta.md

@@ -5,15 +5,15 @@ HTTP Client Meta Document
 
 HTTP requests and responses are the two fundamental objects in web programming.
 All clients communicating to an external API use some form of HTTP client. Many
-libraries are coupled to one specific client or implement a client and/or adapter
-layer themselves. This leads to bad library design, version conflicts, or too much
-code not related to the library domain.
+libraries are coupled to one specific client or implement a client and/or
+adapter layer themselves. This leads to bad library design, version conflicts,
+or code unrelated to the library domain.
 
 ## Why bother?
 
 Thanks to PSR-7 we know how HTTP requests and responses ideally look, but nothing
 defines how a request should be sent and a response received. A common interface for HTTP
-clients will allow libraries to be decoupled from specific implementation such as Guzzle.
+clients will allow libraries to be decoupled from specific implementations.
 
 ## Scope
 
@@ -23,24 +23,23 @@ clients will allow libraries to be decoupled from specific implementation such a
 
 ### Non-Goals
 
-* Support for asynchronous HTTP requests is left for another future PSR;
+* Support for asynchronous HTTP requests is left for another future PSR.
 * This PSR does not define how to configure an HTTP client. It only specifies the
-  default behaviours;
-* This PSR is neutral about the use of middlewares (PSR-15).
+  default behaviours.
+* This PSR is neutral about the use of middleware.
 
 #### Asynchronous HTTP client
 
 The reason asynchronous requests are not covered by this PSR is the lack of a
-common standard for Promises. And an HTTP client PSR should not define its own
-promises. At the time the HTTP client PSR was written there was no final PSR
-for Promises.
+common standard for Promises. Promises are sufficiently complex enough that they
+deserve their own specification, and should not be wrapped into this one.
 
 A separate interface for asynchronous requests can be defined in a separate PSR
-once the Promise PSR is accepted. The method signature for asynchronous requests
-has to be different from the method signature for synchronous requests because
-the return type of asynchronous calls will be a Promise. Thus this PSR is forward
-compatible and clients will be able to implement one or both interfaces as makes
-sense for them.
+once a Promise PSR is accepted. The method signature for asynchronous requests
+MUST be different from the method signature for synchronous requests because
+the return type of asynchronous calls will be a Promise. Thus this PSR is forwards
+compatible, and clients will be able to implement one or both interfaces based
+on the features they wish to expose.
 
 ## Approaches
 
@@ -54,8 +53,8 @@ principle). The PSR does not try to restrict nor define how to configure HTTP cl
 An alternative approach would be to pass configuration to the client. That approach
 would have a few drawbacks:
 
-* Configuration must be defined by the PSR;
-* All clients must support the defined configuration;
+* Configuration must be defined by the PSR.
+* All clients must support the defined configuration.
 * If no configuration is passed to the client, the behavior is unpredictable.
 
 ### Exception Model
@@ -77,8 +76,8 @@ the exception handling in a consuming library would in most cases not be differe
 
 The initial idea was to allow the client to be configured to throw exceptions for responses
 with HTTP status 4xx and 5xx. That approach is not desired because consuming libraries would
-have to check for 4xx and 5xx responses twice. First by verifying the status code on the response and
-then by catching possible exceptions.
+have to check for 4xx and 5xx responses twice: first, by verifying the status code on the response,
+and second by catching potential exceptions.
 
 To make the specification more predictable, it was decided that HTTP clients never will throw
 exceptions for 4xx and 5xx responses.
@@ -87,10 +86,11 @@ exceptions for 4xx and 5xx responses.
 
 The HTTP client PSR has been inspired and created by the [php-http team](https://github.com/orgs/php-http/people).
 Back in 2015, they created HTTPlug as a common interface for HTTP clients. They wanted an
-abstraction that third party libraries could use to not rely on a specific HTTP client
-implementation. A stable version has been tagged in January 2016 and the project has been 
-widely adopted since then. With over 3 million downloads the next two years, it was time
-to convert this "de-facto" standard into a real PSR.
+abstraction that third party libraries could use so as not to rely on a specific HTTP client
+implementation. A stable version was tagged in January 2016, and the project has been 
+widely adopted since then. With over 3 million downloads in the two years
+following the initial stable version, it was time to convert this "de-facto"
+standard into a formal specification.
 
 ## People
 
@@ -111,6 +111,6 @@ to convert this "de-facto" standard into a real PSR.
 * Jermey Lindstrom (Guzzle)
 * Christian Lück (Buzz react)
 * Tobias Nyholm (Editor)
-* Matthew O'Phinney (Zend)
+* Matthew Weier O'Phinney (Zend)
 * Mark Sagi-Kazar (Guzzle)
 * Joel Wurtz (HTTPlug)

proposed/http-client/http-client.md

@@ -12,11 +12,12 @@ interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119).
 ### Client
 
 An HTTP client has the responsibility to send a PSR-7 request and return a PSR-7
-response. Under the hood, the HTTP client MAY modify the request received from the user
-and/or the response received from the server. In this case, the request and the response
-MUST be consistent between the body and headers. For example, a server may return a gzip
-encoded body and the client may decides to decode the body. If the client decodes the body,
-the client MUST also remove the Content-Encoding header and adjust the Content-Length header.
+response. Under the hood, the HTTP client MAY modify the request received from
+the user and/or the response received from the server. In this case, the request
+and the response MUST be consistent between the body and headers. For example, a
+server may return a gzip-encoded body and the client may decide to decode the
+body. If the client decodes the body, the client MUST also remove the
+`Content-Encoding` header and adjust the `Content-Length` header.
 
 ### Exceptions
 
@@ -27,8 +28,8 @@ MUST throw a `Psr\Http\Client\Exception\RequestException`. If there is an error
 with the network or the remote server cannot be reached, the HTTP client MUST throw
 a `Psr\Http\Client\Exception\NetworkException`.
 
-Smaller issues, like wrong HTTP versions, that are not blocking the HTTP client from
-sending the request MUST not cause any exception.
+Smaller issues that do not block the client from sending the request (such as
+invalid HTTP versions) MUST NOT result in exceptions.
 
 If the remote server answers with a response that can be parsed into a PSR-7 response,
 the client MUST NOT throw an exception. For example, response status codes in the
@@ -59,13 +60,13 @@ interface ClientInterface
     /**
      * Sends a PSR-7 request and returns a PSR-7 response.
      *
-     * Every technically correct HTTP response MUST be returned as is, even if it represents an HTTP
+     * Every technically correct HTTP response MUST be returned as-is, even if it represents an HTTP
      * error response or a redirect instruction. The only special case is 1xx responses, which MUST
      * be assembled in the HTTP client.
      *
      * The client MAY do modifications to the Request before sending it. Because PSR-7 objects are
      * immutable, one cannot assume that the object passed to ClientInterface::sendRequest() will be the same
-     * object that is actually sent. For example the Request object that is returned by an exception MAY
+     * object that is actually sent. For example, the Request object that is returned by an exception MAY
      * be a different object than the one passed to sendRequest, so comparison by reference (===) is not possible.
      *
      * {@link https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message-meta.md#why-value-objects}
@@ -74,7 +75,7 @@ interface ClientInterface
      *
      * @return ResponseInterface
      *
-     * @throws \Psr\Http\Client\ClientException If an error happens during processing the request.
+     * @throws \Psr\Http\Client\ClientException If an error happens while processing the request.
      */
     public function sendRequest(RequestInterface $request): ResponseInterface;
 }