Documentation clean-up

Author: ramsey

docs/providers/implementing.md

@@ -7,11 +7,11 @@ permalink: /providers/implementing/
 Implementing a Provider Client
 ==============================
 
-> 💡 **TIP:** You may create new provider clients by copying the layout of an existing package. See the [first party](/providers/league/) and [third party](/providers/thirdparty/) provider clients for good examples.
+> 💡 **TIP** You may create new provider clients by copying the layout of an existing package. See the [first party](/providers/league/) and [third party](/providers/thirdparty/) provider clients for good examples.
 
-**When choosing a name for your package, please don’t use the `league` vendor prefix or the `League` vendor namespace, as this implies it is officially supported.** You should use your own username as the vendor prefix, and prepend `oauth2-` to the package name to make it clear your package works with `league/oauth2-client`.
-
-For example, if your GitHub username is *santa*, and you are implementing the *giftpay* OAuth 2.0 client library, a good name for your Composer package would be `santa/oauth2-giftpay`.
+> ⚠️ **Attention!** When choosing a name for your package, please don’t use the `league` vendor prefix or the `League` vendor namespace, as this implies it is officially supported. You should use your own username as the vendor prefix, and prepend `oauth2-` to the package name to make it clear your package works with `league/oauth2-client`.
+>
+> For example, if your GitHub username is *santa*, and you are implementing the *giftpay* OAuth 2.0 client library, a good name for your Composer package would be `santa/oauth2-giftpay`.
 
 If you are working with an OAuth 2.0 service provider not supported out-of-the-box or by an existing package, you may implement your own. To do so, extend [`League\OAuth2\Client\Provider\AbstractProvider`](https://github.com/thephpleague/oauth2-client/blob/master/src/Provider/AbstractProvider.php) and implement the required abstract methods:
 
@@ -26,7 +26,7 @@ protected function createResourceOwner(array $response, AccessToken $token);
 
 Each of these abstract methods has a comment block defining their expectations and typical behavior. Once you have extended this class, you may follow the [basic usage example](/usage/) using your new provider client class.
 
-If you wish to use your provider client class to make authenticated requests to the service, you will also need to define how you provide the token to the service. If this is done via headers, you should override this method:
+If you wish to use your provider client class to make authenticated requests to the provider, you will also need to define how you provide the token to the service. If this is done via headers, you should override this method:
 
 ```php
 protected function getAuthorizationHeaders($token = null);
@@ -70,7 +70,7 @@ Next, implement the `AbstractProvider::createResourceOwner()` method. This metho
 Make It Available
 ------------------
 
-If you find a package for a certain provider useful, chances are someone else will too! Make your package available by putting it on [packagist](https://packagist.org) and [GitHub](https://github.com)! After it's available, submit a pull request to the [oauth2-client](https://github.com/thephpleague/oauth2-client) repository, adding your provider client to the [provider client list](https://github.com/thephpleague/oauth2-client/blob/master/docs/providers/thirdparty.md).
+If you find a package for a certain provider useful, chances are someone else will too! Make your package available by putting it on [Packagist](https://packagist.org) and [GitHub](https://github.com). After it's available, submit a pull request to the [oauth2-client](https://github.com/thephpleague/oauth2-client) repository, adding your provider client to the [provider client list](https://github.com/thephpleague/oauth2-client/blob/master/docs/providers/thirdparty.md).
 
 Make It Official
 ----------------

docs/providers/league.md

@@ -7,10 +7,6 @@ permalink: /providers/league/
 Official Provider Clients
 =========================
 
-Due to the vast (and ever-growing) number of OAuth 2.0 services that exist, it is impossible to maintain first-party support for every OAuth 2.0 provider without damaging our ability to make this package the best it can be. Therefore, we will only accept very high-quality provider clients into the `league` namespace on a case-by-case basis. We list criteria for acceptance on the  [provider client implementation guide](/providers/implementing/).
-
-There are a [large number of community packages](/providers/thirdparty/) that interface with other systems.
-
 You may use [Composer](https://getcomposer.org) to install any of these packages:
 
 ~~~ bash
@@ -24,3 +20,7 @@ Gateway | Composer Package | Maintainer
 [Google](https://github.com/thephpleague/oauth2-google) | league/oauth2-google | [Woody Gilk](https://github.com/shadowhand)
 [Instagram](https://github.com/thephpleague/oauth2-instagram) | league/oauth2-instagram | [Steven Maguire](https://github.com/stevenmaguire)
 [LinkedIn](https://github.com/thephpleague/oauth2-linkedin) | league/oauth2-linkedin | [Steven Maguire](https://github.com/stevenmaguire)
+
+Due to the vast (and ever-growing) number of OAuth 2.0 services that exist, it is impossible to maintain first-party support for every OAuth 2.0 provider without damaging our ability to make this package the best it can be. Therefore, we will only accept very high-quality provider clients into the `league` namespace on a case-by-case basis. We list criteria for acceptance on the  [provider client implementation guide](/providers/implementing/).
+
+There are a [large number of community packages](/providers/thirdparty/) that integrate with other providers.

docs/usage.md

@@ -7,14 +7,14 @@ title: "Basic Usage"
 Basic Usage
 ===========
 
-> ℹ️ **NOTE:** In most cases, you should use a specific [official](/providers/league/) or [third-party](/providers/thirdparty/) provider client library, rather than this base library alone.
+> ℹ️ **NOTE** In most cases, you should use a specific [official](/providers/league/) or [third-party](/providers/thirdparty/) provider client library, rather than this base library alone.
 
 Authorization Code Grant
 ------------------------
 
-The following example uses the out-of-the-box `GenericProvider` provided by this library. If you're looking for a specific provider client (i.e. Facebook, Google, GitHub, etc.), take a look at our [list of provider client libraries](/providers/league/). **HINT: You're probably looking for a specific provider client.**
+The following example uses the out-of-the-box `GenericProvider` provided by this library. If you're looking for a specific provider client (e.g., Facebook, Google, GitHub, etc.), take a look at our [list of provider client libraries](/providers/league/). **HINT: You're probably looking for a specific provider client.**
 
-The authorization code grant type is the most common grant type used when authenticating users with a third-party service. This grant type utilizes a *client* (this library), a *service provider* (the server), and a *resource owner* (the user with credentials to a protected—or owned—resource) to request access to resources owned by the user. This is often referred to as _3-legged OAuth_, since there are three parties involved.
+The *authorization code* grant type is the most common grant type used when authenticating users with a third-party service. This grant type utilizes a *client* (this library), a *service provider* (the server), and a *resource owner* (the account with credentials to a protected—or owned—resource) to request access to resources owned by the user. This is often referred to as _3-legged OAuth_, since there are three parties involved.
 
 ```php
 $provider = new \League\OAuth2\Client\Provider\GenericProvider([
@@ -120,16 +120,13 @@ if ($existingAccessToken->hasExpired()) {
 Resource Owner Password Credentials Grant
 -----------------------------------------
 
-Some service providers allow you to skip the authorization code step to exchange a user's credentials (username and password) for an access token. This is referred to as the "resource owner password credentials" grant type.
+Some service providers allow you to skip the authorization code step to exchange a user's credentials (username and password) for an access token. This is referred to as the *resource owner password credentials* grant type.
 
 According to [section 1.3.3](http://tools.ietf.org/html/rfc6749#section-1.3.3) of the OAuth 2.0 standard (emphasis added):
 
-> The credentials **should only be used when there is a high degree of trust**
-> between the resource owner and the client (e.g., the client is part of the
-> device operating system or a highly privileged application), and when other
-> authorization grant types are not available (such as an authorization code).
+> The credentials **should only be used when there is a high degree of trust** between the resource owner and the client (e.g., the client is part of the device operating system or a highly privileged application), and when other authorization grant types are not available (such as an authorization code).
 
-**We advise against using this grant type if the service provider supports the authorization code grant type (see above), as this reinforces the [password anti-pattern](https://agentile.com/the-password-anti-pattern), allowing users to think it's okay to trust third-party applications with their usernames and passwords.**
+> 🛑 **DANGER!** We advise against using this grant type if the service provider supports the authorization code grant type (see above), as this reinforces the [password anti-pattern](https://agentile.com/the-password-anti-pattern), allowing users to think it's okay to trust third-party applications with their usernames and passwords.
 
 That said, there are use-cases where the resource owner password credentials grant is acceptable and useful.
 
@@ -162,7 +159,9 @@ try {
 Client Credentials Grant
 ------------------------
 
-When your application acts on its own behalf to access resources it controls or owns in a service provider, it may use the client credentials grant type. This is best used when storing the credentials for your application privately and never exposing them (e.g., through the web browser, etc.) to end-users. This grant type functions like the resource owner password credentials grant type, but it does not request a user's username or password. It uses only the client ID and client secret issued to your client by the service provider.
+When your application acts on its own behalf to access resources it controls or owns in a service provider, it may use the *client credentials* grant type.
+
+The client credentials grant type is best when storing the credentials for your application privately and never exposing them (e.g., through the web browser, etc.) to end-users. This grant type functions like the resource owner password credentials grant type, but it does not request a user's username or password. It uses only the client ID and client secret issued to your client by the service provider.
 
 ```php
 // Note: the GenericProvider requires the `urlAuthorize` option, even though