Add comprehensive documentation and improve test comments

Co-authored-by: enghitalo <63821277+enghitalo@users.noreply.github.com>

Author: Copilot

vlib/os/notify/README.md

@@ -0,0 +1,87 @@
+# os.notify - File Descriptor Event Notification
+
+The `os.notify` module provides cross-platform file descriptor event notification using the best available mechanism for each platform:
+- **Linux**: epoll
+- **macOS/BSD**: kqueue
+- **Other platforms**: Not yet supported
+
+## Usage
+
+```v
+import os
+import os.notify
+
+mut notifier := notify.new()!
+defer {
+    notifier.close() or {}
+}
+
+// Add a file descriptor to watch for read events
+notifier.add(fd, .read)!
+
+// Wait for events (with timeout)
+events := notifier.wait(100 * time.millisecond)
+for event in events {
+    if event.kind.has(.read) {
+        // Handle read event
+    }
+}
+```
+
+## Event Types
+
+- `.read` - Data is available to read
+- `.write` - File descriptor is ready for writing
+- `.peer_hangup` - Peer closed the connection (Linux only)
+- `.exception` - Exceptional condition on file descriptor
+- `.error` - Error occurred (Linux only)
+- `.hangup` - Hangup occurred (Linux only)
+
+## Configuration Flags
+
+- `.edge_trigger` - Edge-triggered notifications (note: behavior differs between Linux and macOS)
+- `.one_shot` - Event is disabled after first notification
+- `.wake_up` - System wake-up event (Linux only)
+- `.exclusive` - Exclusive wake-up (Linux only)
+
+## Platform Differences
+
+### macOS/kqueue vs Linux/epoll
+
+**Event Type Support:**
+- macOS kqueue does **not** support: `.peer_hangup`, `.error`, `.hangup`
+- Linux epoll supports all event types
+
+**Configuration Flags:**
+- macOS kqueue does **not** support: `.wake_up`, `.exclusive`
+- Linux epoll supports all configuration flags
+
+**Edge Trigger Behavior:**
+- Linux epoll (`EPOLLET`): Triggers once when state changes from unreadable to readable
+- macOS kqueue (`EV_CLEAR`): May trigger multiple times even if data is not completely read
+
+When using unsupported features on macOS, the methods will return an error instead of panicking, allowing for graceful degradation.
+
+## Error Handling
+
+All methods that can fail return a `Result` type. Handle errors appropriately:
+
+```v
+notifier.add(fd, .read) or {
+    eprintln('Failed to add fd: ${err}')
+    return
+}
+```
+
+On macOS, attempting to use unsupported features will return an error:
+
+```v
+// This will fail on macOS with an error message
+notifier.add(fd, .hangup) or {
+    eprintln('Error: ${err}') // "kqueue does not support 'hangup' event type"
+}
+```
+
+## Thread Safety
+
+Both `EpollNotifier` (Linux) and `KqueueNotifier` (macOS) use fixed-size arrays for event storage, making them thread-safe for concurrent use.

vlib/os/notify/backend_darwin.c.v

@@ -3,6 +3,16 @@ module notify
 import time
 import os
 
+// This is the macOS/BSD backend for the notify module using kqueue.
+// 
+// kqueue has different capabilities compared to Linux's epoll:
+// - Does not support: peer_hangup, error, hangup event types
+// - Does not support: wake_up, exclusive config flags
+// - Edge triggering (EV_CLEAR) behaves differently than epoll's EPOLLET
+//
+// When unsupported features are requested, functions return errors
+// instead of panicking to allow graceful degradation.
+
 #insert "@VEXEROOT/vlib/os/notify/kqueue.h"
 
 pub struct C.kevent {

vlib/os/notify/backend_linux.c.v

@@ -3,6 +3,11 @@ module notify
 import time
 import os
 
+// This is the Linux backend for the notify module using epoll.
+//
+// epoll supports all event types and config flags defined in the
+// FdNotifier interface, making it the most feature-complete backend.
+
 #include <sys/epoll.h>
 
 pub struct C.epoll_event {

vlib/os/notify/notify_test.c.v

@@ -15,6 +15,8 @@ fn make_pipe() !(int, int) {
 	return -1, -1
 }
 
+// test_level_trigger tests level-triggered mode where events continue
+// to be reported as long as the condition persists (e.g., data available to read)
 fn test_level_trigger() {
 	// currently only linux and macos are supported
 	$if linux || macos {
@@ -36,6 +38,8 @@ fn test_level_trigger() {
 	}
 }
 
+// test_edge_trigger tests edge-triggered mode where events are only
+// reported when the state changes. Note: behavior differs between platforms.
 fn test_edge_trigger() {
 	// currently only linux and macos are supported
 	$if linux || macos {
@@ -84,6 +88,8 @@ fn test_edge_trigger() {
 	}
 }
 
+// test_one_shot tests one-shot mode where an event is only reported once
+// and then must be re-armed to receive further notifications
 fn test_one_shot() {
 	$if linux || macos {
 		mut notifier := notify.new()!
@@ -109,7 +115,7 @@ fn test_one_shot() {
 	}
 }
 
-// Kqueue does not support 'hangup' event type.
+// test_hangup tests hangup event detection (Linux only - kqueue doesn't support it)
 fn test_hangup() {
 	$if linux {
 		mut notifier := notify.new()!
@@ -132,6 +138,7 @@ fn test_hangup() {
 	}
 }
 
+// test_write tests write readiness notification
 fn test_write() {
 	$if linux || macos {
 		mut notifier := notify.new()!
@@ -153,6 +160,7 @@ fn test_write() {
 	}
 }
 
+// test_remove tests removing a file descriptor from the watch list
 fn test_remove() {
 	$if linux || macos {
 		mut notifier := notify.new()!