Update README.md

Closes #150

README.md

@@ -17,7 +17,7 @@ for a general introduction to promises.
 - [Implementation notes](#implementation-notes)
 
 
-# Features
+## Features
 
 - [Promises/A+](https://promisesaplus.com/) implementation.
 - Promise resolution and chaining is handled iteratively, allowing for
@@ -29,15 +29,14 @@ for a general introduction to promises.
   `GuzzleHttp\Promise\Coroutine::of()`.
 
 
-# Quick start
+## Quick Start
 
 A *promise* represents the eventual result of an asynchronous operation. The
 primary way of interacting with a promise is through its `then` method, which
 registers callbacks to receive either a promise's eventual value or the reason
 why the promise cannot be fulfilled.
 
-
-## Callbacks
+### Callbacks
 
 Callbacks are registered with the `then` method by providing an optional 
 `$onFulfilled` followed by an optional `$onRejected` function.
@@ -60,12 +59,11 @@ $promise->then(
 ```
 
 *Resolving* a promise means that you either fulfill a promise with a *value* or
-reject a promise with a *reason*. Resolving a promises triggers callbacks
-registered with the promises's `then` method. These callbacks are triggered
+reject a promise with a *reason*. Resolving a promise triggers callbacks
+registered with the promise's `then` method. These callbacks are triggered
 only once and in the order in which they were added.
 
-
-## Resolving a promise
+### Resolving a Promise
 
 Promises are fulfilled using the `resolve($value)` method. Resolving a promise
 with any value other than a `GuzzleHttp\Promise\RejectedPromise` will trigger
@@ -92,8 +90,7 @@ $promise
 $promise->resolve('reader.');
 ```
 
-
-## Promise forwarding
+### Promise Forwarding
 
 Promises can be chained one after the other. Each then in the chain is a new
 promise. The return value of a promise is what's forwarded to the next
@@ -123,7 +120,7 @@ $promise->resolve('A');
 $nextPromise->resolve('B');
 ```
 
-## Promise rejection
+### Promise Rejection
 
 When a promise is rejected, the `$onRejected` callbacks are invoked with the
 rejection reason.
@@ -140,7 +137,7 @@ $promise->reject('Error!');
 // Outputs "Error!"
 ```
 
-## Rejection forwarding
+### Rejection Forwarding
 
 If an exception is thrown in an `$onRejected` callback, subsequent
 `$onRejected` callbacks are invoked with the thrown exception as the reason.
@@ -195,7 +192,8 @@ $promise
 $promise->reject('Error!');
 ```
 
-# Synchronous wait
+
+## Synchronous Wait
 
 You can synchronously force promises to complete using a promise's `wait`
 method. When creating a promise, you can provide a wait function that is used
@@ -247,8 +245,7 @@ $promise->wait();
 
 > PHP Fatal error:  Uncaught exception 'GuzzleHttp\Promise\RejectionException' with message 'The promise was rejected with value: foo'
 
-
-## Unwrapping a promise
+### Unwrapping a Promise
 
 When synchronously waiting on a promise, you are joining the state of the
 promise into the current state of execution (i.e., return the value of the
@@ -275,18 +272,17 @@ wait function will be the value delivered to promise B.
 **Note**: when you do not unwrap the promise, no value is returned.
 
 
-# Cancellation
+## Cancellation
 
 You can cancel a promise that has not yet been fulfilled using the `cancel()`
 method of a promise. When creating a promise you can provide an optional
 cancel function that when invoked cancels the action of computing a resolution
 of the promise.
 
 
-# API
+## API
 
-
-## Promise
+### Promise
 
 When creating a promise object, you can provide an optional `$waitFn` and
 `$cancelFn`. `$waitFn` is a function that is invoked with no arguments and is
@@ -349,7 +345,7 @@ A promise has the following methods:
   Rejects the promise with the given `$reason`.
 
 
-## FulfilledPromise
+### FulfilledPromise
 
 A fulfilled promise can be created to represent a promise that has been
 fulfilled.
@@ -366,7 +362,7 @@ $promise->then(function ($value) {
 ```
 
 
-## RejectedPromise
+### RejectedPromise
 
 A rejected promise can be created to represent a promise that has been
 rejected.
@@ -383,7 +379,7 @@ $promise->then(null, function ($reason) {
 ```
 
 
-# Promise interop
+## Promise Interoperability
 
 This library works with foreign promises that have a `then` method. This means
 you can use Guzzle promises with [React promises](https://github.com/reactphp/promise)
@@ -409,7 +405,7 @@ a foreign promise. You will need to wrap a third-party promise with a Guzzle
 promise in order to utilize wait and cancel functions with foreign promises.
 
 
-## Event Loop Integration
+### Event Loop Integration
 
 In order to keep the stack size constant, Guzzle promises are resolved
 asynchronously using a task queue. When waiting on promises synchronously, the
@@ -437,10 +433,9 @@ $loop->addPeriodicTimer(0, [$queue, 'run']);
 *TODO*: Perhaps adding a `futureTick()` on each tick would be faster?
 
 
-# Implementation notes
-
+## Implementation Notes
 
-## Promise resolution and chaining is handled iteratively
+### Promise Resolution and Chaining is Handled Iteratively
 
 By shuffling pending handlers from one owner to another, promises are
 resolved iteratively, allowing for "infinite" then chaining.
@@ -476,8 +471,7 @@ all of its pending handlers to the new promise. When the new promise is
 eventually resolved, all of the pending handlers are delivered the forwarded
 value.
 
-
-## A promise is the deferred.
+### A Promise is the Deferred
 
 Some promise libraries implement promises using a deferred object to represent
 a computation and a promise object to represent the delivery of the result of
@@ -505,7 +499,10 @@ $promise->resolve('foo');
 
 ## Upgrading from Function API
 
-A static API was first introduced in 1.4.0, in order to mitigate problems with functions conflicting between global and local copies of the package. The function API will be removed in 2.0.0. A migration table has been provided here for your convenience:
+A static API was first introduced in 1.4.0, in order to mitigate problems with
+functions conflicting between global and local copies of the package. The
+function API will be removed in 2.0.0. A migration table has been provided here
+for your convenience:
 
 | Original Function | Replacement Method |
 |----------------|----------------|
@@ -536,10 +533,12 @@ A static API was first introduced in 1.4.0, in order to mitigate problems with f
 
 If you discover a security vulnerability within this package, please send an email to [email protected]. All security vulnerabilities will be promptly addressed. Please do not disclose security-related issues publicly until a fix has been announced. Please see [Security Policy](https://github.com/guzzle/promises/security/policy) for more information.
 
+
 ## License
 
 Guzzle is made available under the MIT License (MIT). Please see [License File](LICENSE) for more information.
 
+
 ## For Enterprise
 
 Available as part of the Tidelift Subscription