diff --git a/src/lib.rs b/src/lib.rs
index 64c5740b..c9132417 100644
--- a/src/lib.rs
+++ b/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>;
 }