Minor docs improvements, mostly around Verify* plugs (#692)

* Homegeneize lists inside moduledocs for Verify* modules

This will have the additional effect of those lists actually being
rendered as such in the HTML docs.

Also make it clearer that what happens is that any of those conditions
not being met is sufficient.

* Add deprecation notice to VerifyCookie's moduledoc

Consistent with the deprecation attribute in the code

* Clarify that Verify* plugs don't do anything when no relevant token is found

Also, fix the doc for VerifyHeader that refers to the session instead
of to the header.

* Various minor language corrections to the pipelines guide

guides/plug/pipelines.md

@@ -2,9 +2,9 @@
 
 Guardian's Plug support provides an easy and composable way to put together your authentication.
 
-Different parts of your application are going to need different parts of the authentication system. Some areas a user can be logged in, or not. Others users are required.
+Different parts of your application are going to need different parts of the authentication system. For some areas, a user can be logged in, or not. For others users are required.
 
-Guardian's composable nature, coupled with the composable nature of Plug means that the options are pretty much endless. For that reason this documentation will focus on walking through how Guardian pipelines work so you can get just the right solution for you.
+Guardian's composable nature, coupled with the composable nature of Plug provide nearly endless options for customization. For that reason, this documentation will focus on walking through how Guardian pipelines work so you can get just the right solution for you.
 
 ## What is a Guardian Pipeline?
 
@@ -13,11 +13,11 @@ A pipeline provides two main pieces.
 1. Access to your [implementation module](introduction-implementation.html)
 2. An error handler for when folks aren't authenticated
 
-The pipeline puts these two modules into the `Plug.Conn` struct so that they're available to all downstream plugs. This means that we can set these at the start of our plug chain and even swap them out downstream if we need to. More on that later though.
+The pipeline puts these two modules into the `Plug.Conn` struct so that they're available to all downstream plugs. This means that we can set these at the start of our plug chain and even swap them out downstream if we need to. More on that later, though.
 
 ## A manual version
 
-When we `use Guardian.Plug.Pipeline` it's just wrapping up a bunch of plugs for us into a nice neat bundle. In order to understand what it's doing we'll first look at it manually.
+When we `use Guardian.Plug.Pipeline`, it's just wrapping up a bunch of plugs for us into a nice neat bundle. In order to understand what it's doing, we'll first look at it manually.
 
 The first step is to use the pipeline plug to specify the implementation module and error handler.
 
@@ -32,7 +32,7 @@ The next thing that we're going to want to do is find the token. Guardian provid
 
 * [VerifySession](Guardian.Plug.VerifySession.html) - For when the token is stored in the session
 * [VerifyHeader](Guardian.Plug.VerifyHeader.html) - `Authorization` header token location
-* [VerifyCookie](Guardian.Plug.VerifyCookie.html) - A cookie has the token stored
+* [VerifyCookie](Guardian.Plug.VerifyCookie.html) (deprecated) - A cookie has the token stored
 
 ```elixir
 # ...
@@ -165,7 +165,7 @@ It's a good idea to have at least two Phoenix pipelines for authentication.
 1. Find and verify the token if it's provided
 2. Ensure authenticated where appropriate
 
-The `Guardian.Plug.VerifySession` will work fine if sessions are loaded and if they're no it will just move on to the next plug so we can always just check both.
+The `Guardian.Plug.VerifySession` will work fine if sessions are loaded and if they're not it will just move on to the next plug so we can always just check both.
 
 In this example we'll show it without the Pipeline module. Using the pipeline module can tidy things up for you and make it reusable if you're not using Phoenix.
 

lib/guardian/plug/verify_cookie.ex

@@ -3,10 +3,14 @@ if Code.ensure_loaded?(Plug) do
     @moduledoc """
     Looks for and validates a token found in the request cookies.
 
-    In the case where:
+    This module is deprecated in favor of using
+    `Guardian.Plug.VerifySession` or the `Guardian.Plug.VerifyHeader`
+    plug with the `:refresh_from_cookie` option
 
-    a. The cookies are not loaded
-    b. A token is already found for `:key`
+    In the case where either:
+
+    1. The cookies are not loaded
+    2. A token is already found for `:key`
 
     This plug will not do anything.
 

lib/guardian/plug/verify_header.ex

@@ -3,10 +3,10 @@ if Code.ensure_loaded?(Plug) do
     @moduledoc """
     Looks for and validates a token found in the `Authorization` header.
 
-    In the case where:
+    In the case where either:
 
-    1. The session is not loaded
-    2. A token is already found for `:key`
+    1. A token is already found for `:key`
+    2. No token is found in the `Authorization` header.
 
     This plug will not do anything.
 

lib/guardian/plug/verify_session.ex

@@ -3,10 +3,11 @@ if Code.ensure_loaded?(Plug) do
     @moduledoc """
     Looks for and validates a token found in the session.
 
-    In the case where:
+    In the case where either:
 
-    a. The session is not loaded
-    b. A token is already found for `:key`
+    1. The session is not loaded
+    2. A token is already found for `:key`
+    3. No token is found on the session
 
     This plug will not do anything.