docs: improve rename docs

src/backend/KQueue.zig

@@ -189,7 +189,7 @@ fn scan_dir(self: *@This(), allocator: std.mem.Allocator, dir_path: []const u8)
     var dir = std.fs.openDirAbsolute(dir_path, .{ .iterate = true }) catch return;
     defer dir.close();
 
-    // Arena for all temporaries — freed in one shot at the end.
+    // Arena for all temporaries - freed in one shot at the end.
     var arena = std.heap.ArenaAllocator.init(allocator);
     defer arena.deinit();
     const tmp = arena.allocator();

src/backend/KQueueDir.zig

@@ -173,7 +173,7 @@ fn scan_dir(self: *@This(), allocator: std.mem.Allocator, dir_path: []const u8)
     var dir = std.fs.openDirAbsolute(dir_path, .{ .iterate = true }) catch return;
     defer dir.close();
 
-    // Arena for all temporaries — freed in one shot at the end.
+    // Arena for all temporaries - freed in one shot at the end.
     var arena = std.heap.ArenaAllocator.init(allocator);
     defer arena.deinit();
     const tmp = arena.allocator();
@@ -242,13 +242,13 @@ fn scan_dir(self: *@This(), allocator: std.mem.Allocator, dir_path: []const u8)
         var cit = current_files.iterator();
         while (cit.next()) |entry| {
             if (snapshot.getPtr(entry.key_ptr.*)) |stored_mtime| {
-                // File exists in both — check for modification via mtime change.
+                // File exists in both - check for modification via mtime change.
                 if (stored_mtime.* != entry.value_ptr.*) {
                     stored_mtime.* = entry.value_ptr.*;
                     try to_modify.append(tmp, entry.key_ptr.*); // from current_files (tmp)
                 }
             } else {
-                // New file — add to snapshot and to_create list.
+                // New file - add to snapshot and to_create list.
                 const owned = allocator.dupe(u8, entry.key_ptr.*) catch |e| {
                     return e;
                 };

src/types.zig

@@ -18,22 +18,25 @@ pub const EventType = enum {
     ///
     /// Delivery varies by backend:
     ///
-    /// - **INotify**: renames within the watched tree are delivered as a
+    /// - **INotify**: all watches share a single inotify file descriptor, so
-    ///   single atomic `rename` callback with both source and destination
+    ///   moves are paired by cookie across all watched roots. Renames between
-    ///   paths. A move out of the tree appears as `deleted`; a move into
+    ///   two watched directories - even separate watch roots on the same
-    ///   the tree appears as `created`.
+    ///   watcher instance - are delivered as a single atomic `rename`
+    ///   callback. A move out of all watched paths appears as `deleted`; a
+    ///   move in from an unwatched path appears as `created`.
+    ///
+    /// - **Windows**: renames within a single watched root are delivered as a
+    ///   single atomic `rename` callback. However, each root uses an
+    ///   independent `ReadDirectoryChangesW` handle with no shared cookie, so
+    ///   a move between two separately watched roots cannot be paired: it
+    ///   appears as `deleted` on the source side and `created` on the
+    ///   destination side.
     ///
     /// - **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
+    ///   `NOTE_WRITE` events and appear as `deleted` + `created`.
-    ///   name followed by a `created` event for the new name.
-    ///
-    /// - **Windows**: renames within the watched tree are delivered as a
-    ///   single atomic `rename` callback, matching INotify behaviour. A
-    ///   move out of the tree appears as `deleted`; a move into the tree
-    ///   appears as `created`.
     ///
     /// - **FSEvents**: each path involved in a rename receives its own
     ///   `renamed` change event; the two sides are not paired.
@@ -61,9 +64,9 @@ pub const Error = error{
 
 /// Selects how the watcher delivers events to the caller.
 ///
-/// - `.threaded` — the backend spawns an internal thread that calls the
+/// - `.threaded` - the backend spawns an internal thread that calls the
 ///   handler directly. The caller just needs to keep the `Watcher` alive.
-/// - `.polling` — no internal thread is created. The caller must poll
+/// - `.polling` - no internal thread is created. The caller must poll
 ///   `poll_fd()` for readability and call `handle_read_ready()` whenever
 ///   data is available. Currently only supported on Linux (inotify).
 pub const InterfaceType = enum { polling, threaded };