docs: clarify per-backend rename semantics

src/types.zig

@@ -11,11 +11,22 @@ pub const EventType = enum {
     deleted,
     /// A file or directory was renamed or moved.
     ///
-    /// INotify delivers this as a single `rename` callback with both the
+    /// Delivery varies by backend:
-    /// source and destination paths. All other backends (kqueue, FSEvents,
+    ///
-    /// Windows) cannot pair the two sides atomically and emit a `deleted`
+    /// - **INotify**: renames within the watched tree are delivered as a
-    /// event for the old path followed by a `created` event for the new
+    ///   single atomic `rename` callback with both source and destination
-    /// path instead.
+    ///   paths. A move out of the tree appears as `deleted`; a move into
+    ///   the tree appears as `created`.
+    ///
+    /// - **kqueue / kqueuedir**: when a watched *directory* is itself
+    ///   renamed, a `renamed` change event is emitted for the old directory
+    ///   path (the new path is not known). Renames of *files inside* a
+    ///   watched directory are detected indirectly via directory-level
+    ///   `NOTE_WRITE` events and appear as a `deleted` event for the old
+    ///   name followed by a `created` event for the new name.
+    ///
+    /// - **FSEvents / Windows**: each path involved in a rename receives
+    ///   its own `renamed` change event; the two sides are not paired.
     renamed,
 };
 

test_manual.sh

@@ -53,6 +53,22 @@ sleep 0.4
 
 echo "[op] rmdir subdir"
 rmdir "$TESTDIR/subdir"
+sleep 0.4
+
+echo "[op] mkdir dirA"
+mkdir "$TESTDIR/dirA"
+sleep 0.4
+
+echo "[op] touch dirA/file3.txt"
+touch "$TESTDIR/dirA/file3.txt"
+sleep 0.4
+
+echo "[op] rename dirA -> dirB"
+mv "$TESTDIR/dirA" "$TESTDIR/dirB"
+sleep 0.4
+
+echo "[op] rmdir dirB (and contents)"
+rm -rf "$TESTDIR/dirB"
 sleep 0.5
 
 echo ""