Improved documentation for SessionStore and wrap-session

@@ -11,9 +11,10 @@
 
   The following options are available:
     :store
-      An implementation map containing :read, :write, and :delete
-      keys. This determines how the session is stored. Defaults to
-      in-memory storage.
+      An implementation of the SessionStore protocol in the
+      ring.middleware.session.store namespace. This determines how the
+      session is stored. Defaults to in-memory storage
+      (ring.middleware.session.store.MemoryStore).
     :root
       The root path of the session. Anything path above this will not
       be able to see this session. Equivalent to setting the cookie's

@@ -2,6 +2,13 @@
   "Common session store objects and functions.")
 
 (defprotocol SessionStore
-  (read-session [store key] "Read a session map from the store.")
-  (write-session [store key data] "Write a session map to the store.")
-  (delete-session [store key] "Delete a session map from the store."))
+  (read-session [store key]
+    "Read a session map from the store. If the key is not found, an empty map
+    is returned.")
+  (write-session [store key data]
+    "Write a session map to the store. Returns the (possibly changed) key under
+    which the data was stored. If the key is nil, the session is considered
+    to be new, and a fresh key should be generated.")
+  (delete-session [store key]
+    "Delete a session map from the store, and returns the session key. If the
+    returned key is nil, the session cookie will be removed."))