require ISession.invalidate to leave behind a usable session

CHANGES.txt

@@ -14,6 +14,9 @@ Next release
 - ``pyramid.wsgi.wsgiapp`` and ``pyramid.wsgi.wsgiapp2`` now raise
   ``ValueError`` when accidentally passed ``None``.
 
+- Clarify a previously-implied detail of the ``ISession.invalidate`` API
+  documentation.
+
 1.5 (2014-04-08)
 ================
 

pyramid/interfaces.py

@@ -910,7 +910,13 @@ def invalidate():
         ``invalidate`` is implementation-dependent, but it should have
         the effect of completely dissociating any data stored in the
         session with the current request.  It might set response
-        values (such as one which clears a cookie), or it might not."""
+        values (such as one which clears a cookie), or it might not.
+
+        An invalidated session may be used after the call to ``invalidate``
+        with the effect that a new session is created to store the data. This
+        enables workflows requiring an entirely new session, such as in the
+        case of changing privilege levels or preventing fixation attacks.
+        """
 
     def changed():
         """ Mark the session as changed. A user of a session should