@shd101wyy/yo 0.1.12 → 0.1.13

package/std/sync/cond.yo

@@ -1,3 +1,5 @@
+//! Condition variable for thread synchronization.
+
 { __YO_THREAD_SYNC_TYPE, mutex_t, Mutex } :: import "./mutex";
 
 extern "Yo",
@@ -9,6 +11,7 @@ extern "Yo",
   __yo_cond_destroy : (fn(cv : *(__YO_COND_TYPE)) -> unit)
 ;
 
+/// Low-level condition variable (manual lifetime via `destroy`).
 cond_t :: newtype(
   cv : __YO_COND_TYPE
 );
@@ -34,6 +37,7 @@ impl(cond_t,
   })
 );
 
+/// Reference-counted condition variable with automatic cleanup via `Dispose`.
 Cond :: object(
   cv : __YO_COND_TYPE
 );

package/std/sync/mutex.yo

@@ -1,3 +1,5 @@
+//! Mutual exclusion lock primitives.
+
 extern "Yo",
   __YO_THREAD_SYNC_TYPE : Type,
   __yo_mutex_create : (fn() -> __YO_THREAD_SYNC_TYPE),
@@ -6,6 +8,7 @@ extern "Yo",
   __yo_mutex_destroy : (fn(mutex : *(__YO_THREAD_SYNC_TYPE)) -> unit)
 ;
 
+/// Low-level mutex (manual lifetime via `destroy`).
 mutex_t :: newtype(
   mutex : __YO_THREAD_SYNC_TYPE
 );
@@ -27,7 +30,7 @@ impl(mutex_t,
   })
 );
 
-// GC managed
+/// Reference-counted mutex with automatic cleanup via `Dispose`.
 Mutex :: object(
   mutex : __YO_THREAD_SYNC_TYPE
 );

package/std/sync/once.yo

@@ -1,25 +1,23 @@
-// std/sync/once.yo - One-time initialization
-//
-// Execute a function exactly once, thread-safely.
-//
-// Example:
-//   { Once } :: import "std/sync/once";
-//
-//   init := Once.new();
-//   // Only the first call executes the function
-//   init.call(() => {
-//     println("initialized!");
-//   });
-//   init.call(() => {
-//     println("this will NOT run");
-//   });
+//! One-time initialization primitive.
+//!
+//! # Example
+//!
+//! ```rust
+//! { Once } :: import "std/sync/once";
+//!
+//! init := Once.new();
+//! // Only the first call executes the function
+//! init.call(() => {
+//!   println("initialized!");
+//! });
+//! init.call(() => {
+//!   println("this will NOT run");
+//! });
+//! ```
 
 { Mutex } :: import "./mutex";
 
-// ============================================================================
-// Once
-// ============================================================================
-
+/// Execute a function exactly once, thread-safely.
 Once :: object(
   _done  : bool,
   _mutex : Mutex

package/std/sync/rwlock.yo

@@ -1,29 +1,26 @@
-// std/sync/rwlock.yo - Reader-Writer Lock
-//
-// Allows multiple concurrent readers or one exclusive writer.
-// Uses Mutex + Cond internally.
-//
-// Example:
-//   { RwLock } :: import "std/sync/rwlock";
-//
-//   lock := RwLock.new();
-//   // Multiple readers can hold the lock simultaneously
-//   lock.read_lock();
-//   // ... read shared data ...
-//   lock.read_unlock();
-//
-//   // Only one writer at a time, blocks all readers
-//   lock.write_lock();
-//   // ... write shared data ...
-//   lock.write_unlock();
+//! Reader-writer lock allowing multiple concurrent readers or one exclusive writer.
+//!
+//! # Example
+//!
+//! ```rust
+//! { RwLock } :: import "std/sync/rwlock";
+//!
+//! lock := RwLock.new();
+//! // Multiple readers can hold the lock simultaneously
+//! lock.read_lock();
+//! // ... read shared data ...
+//! lock.read_unlock();
+//!
+//! // Only one writer at a time, blocks all readers
+//! lock.write_lock();
+//! // ... write shared data ...
+//! lock.write_unlock();
+//! ```
 
 { Mutex } :: import "./mutex";
 { Cond } :: import "./cond";
 
-// ============================================================================
-// RwLock
-// ============================================================================
-
+/// Reader-writer lock built on `Mutex` and `Cond`.
 RwLock :: object(
   _readers  : i32,
   _writer   : bool,

package/std/sync/waitgroup.yo

@@ -1,30 +1,28 @@
-// std/sync/waitgroup.yo - WaitGroup
-//
-// Wait for a group of tasks to complete. Similar to Go's sync.WaitGroup.
-//
-// Example:
-//   { WaitGroup } :: import "std/sync/waitgroup";
-//   { Thread } :: import "std/thread";
-//
-//   wg := WaitGroup.new();
-//   wg.add(i32(3));
-//   i := i32(0);
-//   while runtime((i < i32(3))), {
-//     t := Thread.spawn(() => {
-//       // ... do work ...
-//       wg.done();
-//     });
-//     i = (i + i32(1));
-//   };
-//   wg.wait();  // blocks until all 3 tasks call done()
+//! Wait for a group of tasks to complete, similar to Go's `sync.WaitGroup`.
+//!
+//! # Example
+//!
+//! ```rust
+//! { WaitGroup } :: import "std/sync/waitgroup";
+//! { Thread } :: import "std/thread";
+//!
+//! wg := WaitGroup.new();
+//! wg.add(i32(3));
+//! i := i32(0);
+//! while runtime((i < i32(3))), {
+//!   t := Thread.spawn(() => {
+//!     // ... do work ...
+//!     wg.done();
+//!   });
+//!   i = (i + i32(1));
+//! };
+//! wg.wait();  // blocks until all 3 tasks call done()
+//! ```
 
 { Mutex } :: import "./mutex";
 { Cond } :: import "./cond";
 
-// ============================================================================
-// WaitGroup
-// ============================================================================
-
+/// Synchronization primitive that blocks until a counter reaches zero.
 WaitGroup :: object(
   _count : i32,
   _mutex : Mutex,

package/std/sys/advise.yo

@@ -1,7 +1,7 @@
-// std/sys/advise.yo - Kernel advisory hints
-//
-// Advisory wrappers for file and memory access pattern hints.
-// Returns 0 on success, -errno / negative platform error on failure.
+//! Kernel advisory hints.
+//!
+//! Advisory wrappers for file and memory access pattern hints.
+//! Returns 0 on success, -errno / negative platform error on failure.
 
 {
   __yo_sync_fadvise,

package/std/sys/bufio/buf_reader.yo

@@ -1,19 +1,22 @@
-// std/sys/bufio/buf_reader.yo - Buffered reader for file descriptors
-//
-// Wraps a file descriptor with an internal buffer for efficient reads.
-// Reduces the number of system calls by reading data in larger chunks.
-//
-// Example:
-//   { BufReader } :: import "std/sys/bufio/buf_reader";
-//   IO_file :: import "std/sys/file";
-//
-//   reader := BufReader.new(fd);
-//   line := io.await(reader.read_line(using(io)));
-//   match(line,
-//     .Ok(.Some(s)) => println(s),
-//     .Ok(.None) => println("EOF"),
-//     .Err(e) => println(e.to_string())
-//   );
+//! Buffered reader for file descriptors.
+//!
+//! Wraps a file descriptor with an internal buffer for efficient reads.
+//! Reduces the number of system calls by reading data in larger chunks.
+//!
+//! # Example
+//!
+//! ```rust
+//! { BufReader } :: import "std/sys/bufio/buf_reader";
+//! IO_file :: import "std/sys/file";
+//!
+//! reader := BufReader.new(fd);
+//! line := io.await(reader.read_line(using(io)));
+//! match(line,
+//!   .Ok(.Some(s)) => println(s),
+//!   .Ok(.None) => println("EOF"),
+//!   .Err(e) => println(e.to_string())
+//! );
+//! ```
 
 { ArrayList } :: import "../../collections/array_list";
 open import "../../string";

package/std/sys/bufio/buf_writer.yo

@@ -1,14 +1,17 @@
-// std/sys/bufio/buf_writer.yo - Buffered writer for file descriptors
-//
-// Wraps a file descriptor with an internal buffer for efficient writes.
-// Reduces the number of system calls by batching small writes together.
-//
-// Example:
-//   { BufWriter } :: import "std/sys/bufio/buf_writer";
-//
-//   writer := BufWriter.new(fd);
-//   io.await(writer.write_string(String.from("hello\n"), using(io)));
-//   io.await(writer.flush(using(io)));
+//! Buffered writer for file descriptors.
+//!
+//! Wraps a file descriptor with an internal buffer for efficient writes.
+//! Reduces the number of system calls by batching small writes together.
+//!
+//! # Example
+//!
+//! ```rust
+//! { BufWriter } :: import "std/sys/bufio/buf_writer";
+//!
+//! writer := BufWriter.new(fd);
+//! io.await(writer.write_string(`hello\n`, using(io)));
+//! io.await(writer.flush(using(io)));
+//! ```
 
 { ArrayList } :: import "../../collections/array_list";
 open import "../../string";

package/std/sys/clock.yo

@@ -1,7 +1,7 @@
-// std/sys/clock.yo - High-resolution clock queries
-//
-// Provides a synchronous wrapper for reading wall-clock and monotonic time.
-// Returns 0 on success, -errno / negative platform error on failure.
+//! High-resolution clock queries.
+//!
+//! Provides a synchronous wrapper for reading wall-clock and monotonic time.
+//! Returns 0 on success, -errno / negative platform error on failure.
 
 { platform, Platform } :: import "../process";
 { __yo_sync_clock_gettime } :: import "./externs.yo";

package/std/sys/constants.yo

@@ -1,8 +1,8 @@
-// std/sys/constants.yo - File system constants
-//
-// File mode bits, permission bits, AT_* flags, open flags,
-// access mode constants, copyfile flags, directory entry types,
-// and default permission modes.
+//! File system constants.
+//!
+//! File mode bits, permission bits, `AT_*` flags, open flags,
+//! access mode constants, copyfile flags, directory entry types,
+//! and default permission modes.
 
 { platform, Platform } :: import "../process";
 

package/std/sys/copy.yo

@@ -1,11 +1,12 @@
-// std/sys/copy.yo - File copy operations
-//
-// Synchronous wrappers for copyfile/sendfile.
-// These are inherently synchronous on all platforms.
-//
-// Return values:
-//   - copyfile: 0 on success, -errno on failure
-//   - sendfile: bytes transferred on success, -errno on failure
+//! File copy operations.
+//!
+//! Synchronous wrappers for `copyfile`/`sendfile`.
+//! These are inherently synchronous on all platforms.
+//!
+//! ## Return values
+//!
+//! - `copyfile`: 0 on success, -errno on failure
+//! - `sendfile`: bytes transferred on success, -errno on failure
 
 { __yo_sync_copyfile, __yo_sync_sendfile } :: import "./externs.yo";
 

package/std/sys/dir.yo

@@ -1,11 +1,12 @@
-// std/sys/dir.yo - Directory operations
-//
-// Provides low-level directory manipulation wrappers around C runtime externs.
-//
-// Async operations (mkdir, unlink, rename, symlink, link, getdents) return IOFuture which resolves to:
-//   - 0 on success (for mkdir, unlink, rename, symlink, link)
-//   - Bytes read for getdents
-//   - Negative value: -errno on failure
+//! Directory operations.
+//!
+//! Provides low-level directory manipulation wrappers around C runtime externs.
+//!
+//! Async operations (`mkdir`, `unlink`, `rename`, `symlink`, `link`, `getdents`)
+//! return `IOFuture` which resolves to:
+//! - 0 on success (for mkdir, unlink, rename, symlink, link)
+//! - Bytes read for getdents
+//! - Negative value: -errno on failure
 //
 // Sync operations (readlink) return i32 directly:
 //   - Bytes read on success

package/std/sys/dns.yo

@@ -1,11 +1,11 @@
-// std/sys/dns.yo - DNS resolution operations
-//
-// Provides async DNS resolution wrapping getaddrinfo/getnameinfo, plus
-// accessors for iterating the linked list of addrinfo results.
-//
-// All async operations return IOFuture which resolves to:
-//   - 0: success
-//   - Non-zero: raw gai_error code (EAI_NONAME, EAI_AGAIN, etc.)
+//! DNS resolution operations.
+//!
+//! Provides async DNS resolution wrapping `getaddrinfo`/`getnameinfo`, plus
+//! accessors for iterating the linked list of `addrinfo` results.
+//!
+//! All async operations return `IOFuture` which resolves to:
+//! - 0: success
+//! - Non-zero: raw `gai_error` code (`EAI_NONAME`, `EAI_AGAIN`, etc.)
 //
 // Example:
 //   { GlobalAllocator } :: import "../allocator";

package/std/sys/errors.yo

@@ -1,6 +1,4 @@
-// std/sys/errors.yo - IOError type
-//
-// Comprehensive I/O error type with errno-to-error mapping.
+//! `IOError` type — comprehensive I/O error type with errno-to-error mapping.
 
 { String } :: import "../string";
 { ToString } :: import "../fmt";
@@ -17,44 +15,75 @@
 // IOError - I/O error type
 // ============================================================================
 
+/// Comprehensive I/O error type with errno-to-error mapping.
 IOError :: enum(
-  // File system errors
+  /// File or directory not found (ENOENT).
   NotFound,
+  /// Permission denied (EACCES, EPERM).
   PermissionDenied,
+  /// File or directory already exists (EEXIST).
   AlreadyExists,
+  /// Not a directory (ENOTDIR).
   NotADirectory,
+  /// Is a directory (EISDIR).
   IsADirectory,
+  /// Directory not empty (ENOTEMPTY).
   DirectoryNotEmpty,
+  /// Broken pipe (EPIPE).
   BrokenPipe,
+  /// Operation would block (EAGAIN, EWOULDBLOCK).
   WouldBlock,
+  /// Invalid argument (EINVAL).
   InvalidInput,
+  /// Interrupted system call (EINTR).
   Interrupted,
+  /// Too many open files (EMFILE, ENFILE).
   TooManyOpenFiles,
+  /// File too large (EFBIG).
   FileTooLarge,
+  /// No space left on device (ENOSPC).
   NoSpace,
+  /// Read-only filesystem (EROFS).
   ReadOnlyFilesystem,
+  /// Cross-device link (EXDEV).
   CrossDeviceLink,
+  /// Too many links (EMLINK).
   TooManyLinks,
+  /// File name too long (ENAMETOOLONG).
   NameTooLong,
+  /// Operation not supported (ENOTSUP, EOPNOTSUPP).
   NotSupported,
+  /// Operation timed out (ETIMEDOUT).
   TimedOut,
+  /// Resource busy (EBUSY).
   Busy,
+  /// Bad file descriptor (EBADF).
   BadFileDescriptor,
+  /// Generic I/O error (EIO).
   IOError,
 
-  // Network errors
+  /// Connection refused (ECONNREFUSED).
   ConnectionRefused,
+  /// Connection reset by peer (ECONNRESET).
   ConnectionReset,
+  /// Connection aborted (ECONNABORTED).
   ConnectionAborted,
+  /// Not connected (ENOTCONN).
   NotConnected,
+  /// Address already in use (EADDRINUSE).
   AddressInUse,
+  /// Address not available (EADDRNOTAVAIL).
   AddressNotAvailable,
+  /// Network unreachable (ENETUNREACH).
   NetworkUnreachable,
+  /// Host unreachable (EHOSTUNREACH).
   HostUnreachable,
+  /// Network is down (ENETDOWN).
   NetworkDown,
+  /// Already connected (EISCONN).
   AlreadyConnected,
 
-  // Generic
+  /// Other error with raw errno code.
   Other(code: i32)
 );
 

package/std/sys/events.yo

@@ -1,4 +1,4 @@
-// std/sys/events.yo - TTY, Poll, and FS Event constants
+//! TTY, Poll, and FS Event constants.
 
 {
   __yo_fs_event_init, __yo_fs_event_start,
@@ -54,7 +54,7 @@ poll_init :: (fn(fd: i32) -> PollHandle)(
 // Start polling for events.
 // Returns 0 on success, -errno on failure.
 poll_start :: (fn(handle: PollHandle, events: i32, callback: PollCallback, user_data: *(u8)) -> i32)(
-  __yo_poll_start(handle.handle, events, __yo_as(callback, *(u8)), user_data)
+  __yo_poll_start(handle.handle, events, unsafe.cast(callback, *(u8)), user_data)
 );
 
 // Stop polling.
@@ -86,7 +86,7 @@ fs_event_init :: (fn() -> FsEventHandle)(
 // Start watching a path.
 // Returns 0 on success, -errno on failure.
 fs_event_start :: (fn(handle: FsEventHandle, path: *(u8), flags: u32, callback: FsEventCallback, user_data: *(u8)) -> i32)(
-  __yo_fs_event_start(handle.handle, path, flags, __yo_as(callback, *(u8)), user_data)
+  __yo_fs_event_start(handle.handle, path, flags, unsafe.cast(callback, *(u8)), user_data)
 );
 
 // Stop watching.

package/std/sys/externs.yo

@@ -1,6 +1,6 @@
-// std/sys/externs.yo - Extern C runtime function declarations
-//
-// All low-level extern functions for async I/O operations.
+//! Extern C runtime function declarations.
+//!
+//! All low-level extern functions for async I/O operations.
 
 { IOFuture } :: import "./future.yo";
 

package/std/sys/fallocate.yo

@@ -1,7 +1,7 @@
-// std/sys/fallocate.yo - File space pre-allocation
-//
-// Synchronous wrapper for fallocate-style allocation.
-// Returns 0 on success, -errno on failure.
+//! File space pre-allocation.
+//!
+//! Synchronous wrapper for `fallocate`-style allocation.
+//! Returns 0 on success, -errno on failure.
 
 { __yo_sync_fallocate } :: import "./externs.yo";
 

package/std/sys/fcntl.yo

@@ -1,9 +1,11 @@
-// std/sys/fcntl.yo - File descriptor control operations
-//
-// Synchronous wrappers for file descriptor flags and close-on-exec flags.
-// Returns:
-//   - getfl/getfd: flags on success, -errno on failure
-//   - setfl/setfd: 0 on success, -errno on failure
+//! File descriptor control operations.
+//!
+//! Synchronous wrappers for file descriptor flags and close-on-exec flags.
+//!
+//! ## Returns
+//!
+//! - `getfl`/`getfd`: flags on success, -errno on failure
+//! - `setfl`/`setfd`: 0 on success, -errno on failure
 
 {
   __yo_sync_fcntl_getfl,

package/std/sys/file.yo

@@ -1,11 +1,10 @@
-// std/sys/file.yo - Async and sync file operations
-//
-// Provides low-level file I/O wrappers around the C runtime externs.
-//
-// Async operations return IOFuture which resolves to:
-//   - Positive value: success (fd for open, bytes for read/write, 0 for others)
-//   - Negative value: -errno on failure
-//
+//! Async and sync file operations.
+//!
+//! Provides low-level file I/O wrappers around the C runtime externs.
+//!
+//! Async operations return `IOFuture` which resolves to:
+//! - Positive value: success (fd for open, bytes for read/write, 0 for others)
+//! - Negative value: -errno on failure
 // Use IOError.from_result() to convert results to Result(i32, IOError).
 //
 // Example:

package/std/sys/future.yo

@@ -1,6 +1,4 @@
-// std/sys/future.yo - IOFuture type
-//
-// Opaque handle to C async I/O future struct.
+//! `IOFuture` type — opaque handle to a C async I/O future struct.
 
 // ============================================================================
 // Extern type for I/O Future

package/std/sys/iov.yo

@@ -1,7 +1,7 @@
-// std/sys/iov.yo - Scatter/gather I/O
-//
-// Synchronous wrappers for vectored file descriptor I/O.
-// Returns byte count on success, -errno / negative platform error on failure.
+//! Scatter/gather I/O.
+//!
+//! Synchronous wrappers for vectored file descriptor I/O.
+//! Returns byte count on success, -errno / negative platform error on failure.
 
 {
   __yo_sync_readv,

package/std/sys/lock.yo

@@ -1,10 +1,10 @@
-// std/sys/lock.yo - Advisory file locking
-//
-// Synchronous wrapper for POSIX flock().
-// Returns 0 on success, -errno on failure.
-//
-// Operations can be OR'd with LOCK_NB for non-blocking.
-// LOCK_NB returns -EWOULDBLOCK (-11) if the lock cannot be acquired immediately.
+//! Advisory file locking.
+//!
+//! Synchronous wrapper for POSIX `flock()`.
+//! Returns 0 on success, -errno on failure.
+//!
+//! Operations can be OR'd with `LOCK_NB` for non-blocking.
+//! `LOCK_NB` returns -EWOULDBLOCK (-11) if the lock cannot be acquired immediately.
 
 { __yo_sync_flock } :: import "./externs.yo";
 

package/std/sys/mmap.yo

@@ -1,11 +1,10 @@
-// std/sys/mmap.yo - Memory-mapped I/O operations
-//
-// Synchronous wrappers for mmap/munmap/mprotect/msync.
-//
-// mmap returns:
-//   - mapped pointer on success
-//   - encoded error pointer on failure (negative errno cast to pointer)
-//
+//! Memory-mapped I/O operations.
+//!
+//! Synchronous wrappers for `mmap`/`munmap`/`mprotect`/`msync`.
+//!
+//! `mmap` returns:
+//! - Mapped pointer on success
+//! - Encoded error pointer on failure (negative errno cast to pointer)
 // Use is_error(ptr) and error_code(ptr) to detect/decode mmap failures.
 
 { platform, Platform } :: import "../process";

package/std/sys/path.yo

@@ -1,10 +1,7 @@
-// std/sys/path.yo - Path resolution
-//
-// Synchronous wrapper for realpath.
-// This is inherently synchronous on all platforms.
-//
-// Return values:
-//   - realpath: 0 on success, -errno on failure
+//! Path resolution.
+//!
+//! Synchronous wrapper for `realpath`.
+//! Returns 0 on success, -errno on failure.
 
 { __yo_sync_realpath } :: import "./externs.yo";
 

package/std/sys/perm.yo

@@ -1,11 +1,11 @@
-// std/sys/perm.yo - File permission and access operations
-//
-// Provides synchronous wrappers for chmod, chown, and access operations.
-// All operations return i32 directly (no IOFuture overhead).
-//
-// Returns:
-//   - 0: success
-//   - Negative value: -errno on failure
+//! File permission and access operations.
+//!
+//! Provides synchronous wrappers for `chmod`, `chown`, and `access` operations.
+//! All operations return `i32` directly (no `IOFuture` overhead).
+//!
+//! Returns:
+//! - 0: success
+//! - Negative value: -errno on failure
 //
 // Example:
 //   perm :: import "std/sys/perm";