improve snapshot docs

Using two snapshots from the same thread isn't really very easy to do,
so we don't have to warn about that really (it's really nested use of
snapshots that's a problem, and to do that you have to use thread-locals
or something just to get the snapshot *into* the database -- at that
point, something is really going wrong)).

src/lib.rs

@@ -288,11 +288,20 @@ pub trait ParallelDatabase: Database + Send {
     /// }
     /// ```
     ///
+    /// # Panics
+    ///
+    /// It is not permitted to create a snapshot from inside of a
+    /// query. Attepting to do so will panic.
+    ///
     /// # Deadlock warning
     ///
-    /// This second handle is intended to be used from a separate
-    /// thread. Using two database handles from the **same thread**
-    /// can lead to deadlock.
+    /// The intended pattern for snapshots is that, once created, they
+    /// are sent to another thread and used from there. As such, the
+    /// `snapshot` acquires a "read lock" on the database --
+    /// therefore, so long as the `snapshot` is not dropped, any
+    /// attempt to `set` a value in the database will block. If the
+    /// `snapshot` is owned by the same thread that is attempting to
+    /// `set`, this will cause a problem.
     fn snapshot(&self) -> Snapshot<Self>;
 }