diff --git a/src/filesystem/directory.rs b/src/filesystem/directory.rs
index 46dad48..5cfc5f0 100644
--- a/src/filesystem/directory.rs
+++ b/src/filesystem/directory.rs
@@ -144,6 +144,14 @@ where
     }
 
     /// Call a callback function for each directory entry in a directory.
+    ///
+    /// <div class="warning">
+    ///
+    /// Do not attempt to call any methods on the VolumeManager or any of its
+    /// handles from inside the callback. You will get a lock error because the
+    /// object is already locked in order to do the iteration.
+    ///
+    /// </div>
     pub fn iterate_dir<F>(&self, func: F) -> Result<(), Error<D::Error>>
     where
         F: FnMut(&DirEntry),
diff --git a/src/lib.rs b/src/lib.rs
index c1a610f..901101d 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -204,7 +204,8 @@ where
     DirAlreadyExists,
     /// The filesystem tried to gain a lock whilst already locked.
     ///
-    /// This is a bug in the filesystem. Please open an issue.
+    /// This is either a bug in the filesystem, or you tried to access the
+    /// filesystem API from inside a directory iterator (that isn't allowed).
     LockError,
 }
 
diff --git a/src/volume_mgr.rs b/src/volume_mgr.rs
index 3098d69..130e309 100644
--- a/src/volume_mgr.rs
+++ b/src/volume_mgr.rs
@@ -377,6 +377,14 @@ where
     }
 
     /// Call a callback function for each directory entry in a directory.
+    ///
+    /// <div class="warning">
+    ///
+    /// Do not attempt to call any methods on the VolumeManager or any of its
+    /// handles from inside the callback. You will get a lock error because the
+    /// object is already locked in order to do the iteration.
+    ///
+    /// </div>
     pub fn iterate_dir<F>(&self, directory: RawDirectory, func: F) -> Result<(), Error<D::Error>>
     where
         F: FnMut(&DirEntry),