redocument relationship between get_csrf_token and new_csrf_token

1 files changed, 28 insertions, 24 deletions

diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index 842b838cd..0ed52b563 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -298,24 +298,6 @@ post.  To use CSRF token support, you must enable a :term:`session factory`
 as described in :ref:`using_the_default_session_factory` or
 :ref:`using_alternate_session_factories`.
 
-Using the ``session.new_csrf_token`` Method
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To add a CSRF token to the session, use the ``session.new_csrf_token()`` method.
-
-.. code-block:: python
-
-   token = request.session.new_csrf_token()
-
-The ``new_csrf_token()`` method accepts no arguments.  It returns a *token*
-string, which will be opaque and randomized.  This token will also be set
-into the session, awaiting pickup by the ``session.get_csrf_token()`` method.
-You can subsequently use the returned token as the value of a hidden field in
-a form that posts to a method that requires elevated privileges.  The handler
-for the form post should use ``session.get_csrf_token()`` (explained below) to
-obtain the current CSRF token related to the user from the session, and
-compare it to the value of the hidden form field.
-
 Using the ``session.get_csrf_token`` Method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -326,12 +308,20 @@ To get the current CSRF token from the session, use the
 
    token = request.session.get_csrf_token()
 
-The ``get_csrf_token()`` method accepts no arguments.  It returns the "current"
-*token* string generated by the last call to ``session.new_csrf_token()``.  You can
-then use it to compare against the token provided within form post hidden
-value data.  For example, if your form rendering included the CSRF token
-obtained via ``session.new_csrf_token()`` as a hidden input field named
-``csrf_token()``:
+The ``session.get_csrf_token()`` method accepts no arguments.  It returns a
+CSRF *token* string. If ``session.get_csrf_token()`` or
+``session.new_csrf_token()`` was invoked previously for this session, the
+existing token will be returned.  If no CSRF token previously existed for
+this session, a new token will be will be set into the session and returned.
+The newly created token will be opaque and randomized.
+
+You can use the returned token as the value of a hidden field in a form that
+posts to a method that requires elevated privileges.  The handler for the
+form post should use ``session.get_csrf_token()`` *again* to obtain the
+current CSRF token related to the user from the session, and compare it to
+the value of the hidden form field.  For example, if your form rendering
+included the CSRF token obtained via ``session.get_csrf_token()`` as a hidden
+input field named ``csrf_token``:
 
 .. code-block:: python
    :linenos:
@@ -340,3 +330,17 @@ obtained via ``session.new_csrf_token()`` as a hidden input field named
    if token != request.POST['csrf_token']:
        raise ValueError('CSRF token did not match')
 
+Using the ``session.new_csrf_token`` Method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To explicitly add a new CSRF token to the session, use the
+``session.new_csrf_token()`` method.  This differs only from
+``session.get_csrf_token()`` inasmuch as it clears any existing CSRF token,
+creates a new CSRF token, sets the token into the session, and returns the
+token.
+
+.. code-block:: python
+
+   token = request.session.new_csrf_token()
+
+