fix #292 improve volatile attribute documentation

CHANGES.rst

@@ -5,6 +5,8 @@
 5.6.0 (unreleased)
 ==================
 
+- Improve volatile attribute ``_v_`` documentation.
+
 - Make repozo's recover mode atomic by recovering the backup in a
   temporary file which is then moved to the expected output file.
 

doc/guide/writing-persistent-objects.rst

@@ -264,18 +264,31 @@ _p_jar
   commonly used by database-aware application code to get hold of an
   object's database connection.
 
-Attributes with names starting with ``_v_`` are treated as volatile.
-They aren't saved to the database.  They're useful for caching data
-that can be computed from saved data and shouldn't be saved [#cache]_.
-They should be treated as though they can disappear between
-transactions.  Setting a volatile attribute doesn't cause an object to
-be considered to be modified.
-
 An object's ``__dict__`` attribute is treated specially in that
 getting it doesn't cause an object's state to be loaded.  It may have
 the value ``None`` rather than a dictionary for :ref:`ghosts
 <ghost-label>`.
 
+Volatile Attributes
+-------------------
+
+Attributes with names starting with ``_v_`` are treated as volatile.
+They are useful for caching data that can be computed from saved data
+and should not be saved [#cache]_.
+
+They are never serialized and not saved to the database.
+Volatile attributes are local to a specific active object in memory and
+thus to a specific connection.
+They should be treated as though they can disappear between transactions:
+If an object is removed from the connection cache the volatile attribute is
+gone.
+
+Because ZODB connections can be used (in a serial fashion) from one thread
+and then another, it is possible to see volatile attributes that were set
+in one thread in a process appear in another thread in that process.
+
+Setting a volatile attribute does not cause an object to be considered to
+be modified.
 
 Object storage and management
 =============================