Index: Doc/library/shelve.rst
===================================================================
--- Doc/library/shelve.rst	(revision 74875)
+++ Doc/library/shelve.rst	(working copy)
@@ -42,16 +42,28 @@
 Shelf objects support all methods supported by dictionaries.  This eases the
 transition from dictionary based scripts to those requiring persistent storage.
 
-One additional method is supported:
+Two additional methods are supported:
 
 
 .. method:: Shelf.sync()
 
-   Write back all entries in the cache if the shelf was opened with *writeback* set
-   to *True*. Also empty the cache and synchronize the persistent dictionary on
-   disk, if feasible.  This is called automatically when the shelf is closed with
-   :meth:`close`.
+   Write back all entries in the cache if the shelf was opened with *writeback*
+   set to :const:`True`. Also empty the cache and synchronize the persistent
+   dictionary on disk, if feasible.  This is called automatically when the
+   shelf is closed with :meth:`close`.
 
+.. method:: Shelf.close()
+
+   Synchronize and close the persistent *dict* object. Operations on a closed
+   shelf will fail. :meth:`close` is automatically called by :meth:`__del__`.
+
+
+.. attention::
+
+   If *writeback* is :const:`True` and you performed operations on mutable
+   items always :meth:`sync <Shelf.sync>` or :meth:`close <Shelf.close>` the
+   shelf. Otherwise all your modifications will be lost on program exit.
+
 .. seealso::
 
    `Persistent dictionary recipe <http://code.activestate.com/recipes/576642/>`_
@@ -75,11 +87,6 @@
   database should be fairly small, and in rare cases key collisions may cause the
   database to refuse updates.
 
-* Depending on the implementation, closing a persistent dictionary may or may
-  not be necessary to flush changes to disk.  The :meth:`__del__` method of the
-  :class:`Shelf` class calls the :meth:`close` method, so the programmer generally
-  need not do this explicitly.
-
 * The :mod:`shelve` module does not support *concurrent* read/write access to
   shelved objects.  (Multiple simultaneous read accesses are safe.)  When a
   program has a shelf open for writing, no other program should have it open for