514: Document need for req.user

docs/authentication.rst

@@ -36,6 +36,10 @@ To use cookie authentication, simply use the ``loginRequired`` middleware::
       res.send('Hello, ' + req.user.fullname);
     });
 
+.. tip::
+    See :ref:`getUser` to learn how to use the getUser
+    middleware to access the current user account.
+
 Behind the scenes we are issuing a OAuth2 Access Token and Refresh Token for
 the user, and storing them in secure, HTTPS-Only cookies.  After the user has
 logged in, these cookies will be supplied on every request.  Our library will
@@ -185,6 +189,10 @@ of how you can create an API Key for the currently logged in user::
       });
     });
 
+.. tip::
+    See :ref:`getUser` to learn how to use the getUser
+    middleware to access the current user account.
+
 This is a naive example which simply prints out the API Keys for the user, but
 once they have the keys they will be able to authenticate with your API.
 
@@ -237,6 +245,10 @@ middleware::
       });
     });
 
+.. tip::
+    See :ref:`getUser` to learn how to use the getUser
+    middleware to access the current user account.
+
 
 OAuth2 Client Credentials
 -------------------------
@@ -343,6 +355,10 @@ you need to use the ``apiAuthenticationRequired`` middleware::
       });
     });
 
+.. tip::
+    See :ref:`getUser` to learn how to use the getUser
+    middleware to access the current user account.
+
 By default the Access Tokens are valid for one hour.  If you want to change
 the expiration of these tokens you will need to configure it in the server
 configuration, like this::

docs/user_data.rst

@@ -33,6 +33,14 @@ but we need to know if the user is logged in.  In this case we use the
       }
     });
 
+Alternatively, you can require the middleware like this if you want to access
+the current user on every route: ``app.use(stormpath.getUser);``
+
+.. note::
+  This will always make req.user available if the user is logged in. However,
+  this should not be added if you have routes (such as public asset routes)
+  that do not depend on this middleware.
+
 Forcing Authentication
 ......................
 
@@ -110,6 +118,10 @@ model::
       }
     });
 
+.. tip::
+    See :ref:`getUser` to learn how to use the getUser
+    middleware to access the current user account.
+
 As you can see above -- storing custom information on a ``user`` account is
 extremely simple!
 
@@ -135,6 +147,10 @@ they are statically available inside your handler::
       res.json(req.user.customData);
     });
 
+  .. tip::
+    See :ref:`getUser` to learn how to use the getUser
+    middleware to access the current user account.
+
 Without enabling this expansion, the response would only contain
 an object which has an href to the resource, that would look
 like this::
@@ -145,7 +161,7 @@ like this::
 
 .. note::
 
- Custom data is expanded automatically, but you can disable this
+ Custom data is expanded automatically, but you can disable this.
 
 You can expand any of these *"linked resources"*:
 
@@ -179,6 +195,10 @@ Below is an example which shows how you can iterate over a collection resource
       });
     });
 
+.. tip::
+    See :ref:`getUser` to learn how to use the getUser
+    middleware to access the current user account.
+
 Each collection resource has an ``each`` method which takes in two functions
 with signature: ``function (data, callback), function ()``.  The first function
 will be called for each resource in the collection.  The second function will be