@shd101wyy/yo 0.1.12 → 0.1.13

package/std/sys/pipe.yo

@@ -1,11 +1,12 @@
-// std/sys/pipe.yo - Pipe and file descriptor duplication operations
-//
-// Synchronous wrappers for pipe/dup/dup2.
-// These are inherently synchronous kernel operations on all platforms.
-//
-// Return values:
-//   - pipe: 0 on success, -errno on failure
-//   - dup/dup2: new fd on success, -errno on failure
+//! Pipe and file descriptor duplication operations.
+//!
+//! Synchronous wrappers for `pipe`/`dup`/`dup2`.
+//! These are inherently synchronous kernel operations on all platforms.
+//!
+//! ## Return values
+//!
+//! - `pipe`: 0 on success, -errno on failure
+//! - `dup`/`dup2`: new fd on success, -errno on failure
 
 { __yo_sync_pipe, __yo_sync_dup, __yo_sync_dup2 } :: import "./externs.yo";
 

package/std/sys/process.yo

@@ -1,11 +1,11 @@
-// std/sys/process.yo - Child process management
-//
-// Provides cross-platform child process spawning, waiting, and signal delivery.
-// All async operations return IOFuture which resolves to:
-//   - Positive value: success (pid for spawn, status for waitpid)
-//   - Negative value: -errno on failure
-//
-// argv/envp are NULL-terminated arrays of C strings.
+//! Child process management.
+//!
+//! Provides cross-platform child process spawning, waiting, and signal delivery.
+//! All async operations return `IOFuture` which resolves to:
+//! - Positive value: success (pid for spawn, status for waitpid)
+//! - Negative value: -errno on failure
+//!
+//! `argv`/`envp` are NULL-terminated arrays of C strings.
 // Use `?*(u8)` for entries so .None can be used as the terminator.
 
 { IOFuture } :: import "./future.yo";

package/std/sys/seek.yo

@@ -1,7 +1,7 @@
-// std/sys/seek.yo - File position control
-//
-// Synchronous wrapper for lseek.
-// Returns resulting absolute file offset on success, -errno on failure.
+//! File position control.
+//!
+//! Synchronous wrapper for `lseek`.
+//! Returns resulting absolute file offset on success, -errno on failure.
 
 { __yo_sync_lseek } :: import "./externs.yo";
 

package/std/sys/signal.yo

@@ -1,6 +1,6 @@
-// std/sys/signal.yo - Signal handling functions
-//
-// Provides low-level wrappers for signal registration and delivery.
+//! Signal handling functions.
+//!
+//! Provides low-level wrappers for signal registration and delivery.
 
 { __yo_signal_start, __yo_signal_stop, __yo_kill } :: import "./externs.yo";
 
@@ -9,7 +9,7 @@ SignalHandler :: (fn(data: *(u8)) -> unit);
 // Register a signal handler.
 // Returns 0 on success, -errno on failure.
 on_signal :: (fn(signum: i32, handler: SignalHandler) -> i32)({
-  __yo_signal_start(signum, __yo_as(handler, *(u8)))
+  __yo_signal_start(signum, unsafe.cast(handler, *(u8)))
 });
 
 // Remove a signal handler (reset to default).

package/std/sys/signals.yo

@@ -1,7 +1,7 @@
-// std/sys/signals.yo - POSIX signal constants
-//
-// Platform-aware signal numbers.
-// Uses process.platform for values that differ between Linux and macOS.
+//! POSIX signal constants.
+//!
+//! Platform-aware signal numbers.
+//! Uses `process.platform` for values that differ between Linux and macOS.
 
 { platform, Platform } :: import "../process";
 

package/std/sys/socket.yo

@@ -1,7 +1,7 @@
-// std/sys/socket.yo - Socket constants
-//
-// Platform-aware socket constants for TCP, UDP, and Unix domain sockets.
-// Uses process.platform for values that differ between Linux and macOS.
+//! Socket constants.
+//!
+//! Platform-aware socket constants for TCP, UDP, and Unix domain sockets.
+//! Uses `process.platform` for values that differ between Linux and macOS.
 
 { platform, Platform } :: import "../process";
 {

package/std/sys/socketpair.yo

@@ -1,7 +1,7 @@
-// std/sys/socketpair.yo - Connected socket pair
-//
-// Synchronous wrapper for socketpair-like behavior.
-// Returns 0 on success, negative error on failure.
+//! Connected socket pair.
+//!
+//! Synchronous wrapper for `socketpair`-like behavior.
+//! Returns 0 on success, negative error on failure.
 
 { __yo_sync_socketpair } :: import "./externs.yo";
 

package/std/sys/sockinfo.yo

@@ -1,7 +1,7 @@
-// std/sys/sockinfo.yo - Socket address and option query helpers
-//
-// Synchronous wrappers for socket metadata operations.
-// Returns 0 on success, -errno (or negative platform socket error) on failure.
+//! Socket address and option query helpers.
+//!
+//! Synchronous wrappers for socket metadata operations.
+//! Returns 0 on success, -errno (or negative platform socket error) on failure.
 
 {
   __yo_sync_getsockname,

package/std/sys/statfs.yo

@@ -1,11 +1,11 @@
-// std/sys/statfs.yo - Filesystem statistics
-//
-// Provides a synchronous wrapper around statfs and typed accessors
-// for the statfs buffer returned by the C runtime.
-//
-// All operations return i32 directly (no IOFuture overhead):
-//   - 0 on success
-//   - Negative value: -errno on failure
+//! Filesystem statistics.
+//!
+//! Provides a synchronous wrapper around `statfs` and typed accessors
+//! for the statfs buffer returned by the C runtime.
+//!
+//! All operations return `i32` directly (no `IOFuture` overhead):
+//! - 0 on success
+//! - Negative value: -errno on failure
 //
 // Example:
 //   statfs :: import "std/sys/statfs";

package/std/sys/statx.yo

@@ -1,7 +1,7 @@
-// std/sys/statx.yo - Statx file status type
-//
-// Object wrapper around the C statx buffer, providing
-// accessor methods for file metadata.
+//! Statx file status type.
+//!
+//! Object wrapper around the C statx buffer, providing
+//! accessor methods for file metadata.
 
 {
   S_IFMT, S_IFREG, S_IFDIR, S_IFLNK

package/std/sys/sysinfo.yo

@@ -1,7 +1,7 @@
-// std/sys/sysinfo.yo - Runtime system identification
-//
-// Synchronous wrappers for uname/gethostname.
-// Returns 0 on success, -errno / negative platform error on failure.
+//! Runtime system identification.
+//!
+//! Synchronous wrappers for `uname`/`gethostname`.
+//! Returns 0 on success, -errno / negative platform error on failure.
 
 { platform, Platform } :: import "../process";
 {

package/std/sys/tcp.yo

@@ -1,11 +1,11 @@
-// std/sys/tcp.yo - Async TCP socket operations
-//
-// Provides TCP socket wrappers around the low-level C runtime externs.
-// Uses the socket address helpers to construct sockaddr_in/sockaddr_in6 buffers.
-//
-// All async operations return IOFuture which resolves to:
-//   - Positive value: success (fd for socket/accept, bytes for send/recv, 0 for others)
-//   - Negative value: -errno on failure
+//! Async TCP socket operations.
+//!
+//! Provides TCP socket wrappers around the low-level C runtime externs.
+//! Uses the socket address helpers to construct `sockaddr_in`/`sockaddr_in6` buffers.
+//!
+//! All async operations return `IOFuture` which resolves to:
+//! - Positive value: success (fd for socket/accept, bytes for send/recv, 0 for others)
+//! - Negative value: -errno on failure
 //
 // Example:
 //   { GlobalAllocator } :: import "../allocator.yo";

package/std/sys/temp.yo

@@ -1,11 +1,12 @@
-// std/sys/temp.yo - Temporary file/directory operations
-//
-// Synchronous wrappers for mkdtemp/mkstemp.
-// These are inherently synchronous on all platforms.
-//
-// Return values:
-//   - mkdtemp: 0 on success, -errno on failure
-//   - mkstemp: fd on success, -errno on failure
+//! Temporary file/directory operations.
+//!
+//! Synchronous wrappers for `mkdtemp`/`mkstemp`.
+//! These are inherently synchronous on all platforms.
+//!
+//! ## Return values
+//!
+//! - `mkdtemp`: 0 on success, -errno on failure
+//! - `mkstemp`: fd on success, -errno on failure
 
 { __yo_sync_mkdtemp, __yo_sync_mkstemp } :: import "./externs.yo";
 

package/std/sys/time.yo

@@ -1,11 +1,11 @@
-// std/sys/time.yo - File timestamp operations
-//
-// Provides synchronous wrappers for utime/futime/lutime to change file timestamps.
-// All operations return i32 directly (no IOFuture overhead).
-//
-// Returns:
-//   - 0: success
-//   - Negative value: -errno on failure
+//! File timestamp operations.
+//!
+//! Provides synchronous wrappers for `utime`/`futime`/`lutime` to change file timestamps.
+//! All operations return `i32` directly (no `IOFuture` overhead).
+//!
+//! Returns:
+//! - 0: success
+//! - Negative value: -errno on failure
 //
 // Timestamps use (seconds, nanoseconds) pairs for both atime and mtime.
 // Use special value UTIME_NOW (0x3fffffff) to set current time,

package/std/sys/timer.yo

@@ -1,11 +1,10 @@
-// std/sys/timer.yo - Async timer operations
-//
-// Provides high-level async timer functions:
-//   sleep(ms)   - async sleep for the given number of milliseconds
-//
-// Returns an IOFuture that resolves to a positive value on success
-// (timerfd read size on Linux) or a negative errno.
-// Use with `await` in async contexts.
+//! Async timer operations.
+//!
+//! Provides high-level async timer functions:
+//! - `sleep(ms)` — async sleep for the given number of milliseconds
+//!
+//! Returns an `IOFuture` that resolves to a positive value on success
+//! or a negative errno. Use with `await` in async contexts.
 //
 // Example:
 //   IO :: import "std/io";

package/std/sys/tty.yo

@@ -1,33 +1,36 @@
-// std/sys/tty.yo - TTY operations
+//! TTY operations.
 
 { __yo_tty_init, __yo_tty_set_mode, __yo_tty_reset_mode, __yo_tty_get_winsize, __yo_isatty } :: import "./externs.yo";
 { TTY_MODE_NORMAL, TTY_MODE_RAW, TTY_MODE_IO } :: import "./events.yo";
 
+/// Terminal window size.
 WinSize :: struct(
+  /// Width in columns.
   width : i32,
+  /// Height in rows.
   height : i32
 );
 
-// Initialize TTY for a fd.
-// Returns 0 on success, -errno on failure.
+/// Initialize TTY for a fd.
+/// Returns 0 on success, -errno on failure.
 tty_init :: (fn(fd: i32) -> i32)(
   __yo_tty_init(fd)
 );
 
-// Set TTY mode (normal, raw, IO).
-// Returns 0 on success, -errno on failure.
+/// Set TTY mode (normal, raw, IO).
+/// Returns 0 on success, -errno on failure.
 tty_set_mode :: (fn(fd: i32, mode: i32) -> i32)(
   __yo_tty_set_mode(fd, mode)
 );
 
-// Reset TTY to original mode.
-// Returns 0 on success, -errno on failure.
+/// Reset TTY to original mode.
+/// Returns 0 on success, -errno on failure.
 tty_reset :: (fn() -> i32)(
   __yo_tty_reset_mode()
 );
 
-// Get terminal window size.
-// Returns width and height (0,0 on error).
+/// Get terminal window size.
+/// Returns width and height (0,0 on error).
 tty_winsize :: (fn(fd: i32) -> WinSize)({
   buf_uninit := MaybeUninit(Array(i32, usize(2))).new();
   buf := *(i32)(buf_uninit.as_ptr());
@@ -43,7 +46,7 @@ tty_winsize :: (fn(fd: i32) -> WinSize)({
   WinSize(width, height)
 });
 
-// Check if fd is a TTY.
+/// Check if `fd` is a TTY.
 isatty :: (fn(fd: i32) -> bool)({
   res := __yo_isatty(fd);
   (res > i32(0))

package/std/sys/udp.yo

@@ -1,11 +1,11 @@
-// std/sys/udp.yo - Async UDP socket operations
-//
-// Provides UDP socket wrappers around the low-level C runtime externs.
-// Reuses SockAddr and address helpers from tcp.yo.
-//
-// All async operations return IOFuture which resolves to:
-//   - Positive value: success (fd for socket, bytes for sendto/recvfrom, 0 for others)
-//   - Negative value: -errno on failure
+//! Async UDP socket operations.
+//!
+//! Provides UDP socket wrappers around the low-level C runtime externs.
+//! Reuses `SockAddr` and address helpers from `tcp.yo`.
+//!
+//! All async operations return `IOFuture` which resolves to:
+//! - Positive value: success (fd for socket, bytes for sendto/recvfrom, 0 for others)
+//! - Negative value: -errno on failure
 //
 // Example:
 //   { GlobalAllocator } :: import "../allocator.yo";

package/std/sys/umask.yo

@@ -1,7 +1,7 @@
-// std/sys/umask.yo - Process file creation mask
-//
-// Synchronous wrapper for setting process umask.
-// Returns previous mask value.
+//! Process file creation mask.
+//!
+//! Synchronous wrapper for setting process `umask`.
+//! Returns previous mask value.
 
 { __yo_sync_umask } :: import "./externs.yo";
 

package/std/sys/unix.yo

@@ -1,8 +1,8 @@
-// std/sys/unix.yo - Unix domain socket operations
-//
-// Provides Unix domain socket wrappers around the low-level C runtime externs.
-// Reuses the socket ops (bind/listen/accept/connect/send/recv/close) from the
-// generic socket externs. Uses sockaddr_un helpers to build address buffers.
+//! Unix domain socket operations.
+//!
+//! Provides Unix domain socket wrappers around the low-level C runtime externs.
+//! Reuses the socket ops (bind/listen/accept/connect/send/recv/close) from the
+//! generic socket externs. Uses `sockaddr_un` helpers to build address buffers.
 
 { GlobalAllocator } :: import "../allocator.yo";
 { malloc, free } :: GlobalAllocator;

package/std/testing/bench.yo

@@ -1,12 +1,16 @@
-// std/testing/bench.yo - Micro-benchmarking utilities
-//
-// Runs a function N times, measures elapsed nanoseconds, and returns statistics.
-//
-// Example:
-//   { bench } :: import "std/testing/bench";
-//
-//   result := bench(String.from("sort"), u64(1000), () => { /* ... */ });
-//   println(result.to_string());
+//! Micro-benchmarking utilities.
+//!
+//! Runs a function N times, measures elapsed nanoseconds, and returns statistics
+//! (average, min, max).
+//!
+//! # Example
+//!
+//! ```rust
+//! { bench } :: import "std/testing/bench";
+//!
+//! result := bench(`sort`, u64(1000), () => { /* work */ });
+//! println(result.to_string());
+//! ```
 
 open import "../string";
 { ToString } :: import "../fmt";
@@ -17,12 +21,19 @@ open import "../string";
 // BenchResult
 // ============================================================================
 
+/// Timing statistics returned by `bench`.
 BenchResult :: struct(
+  /// Benchmark name.
   name       : String,
+  /// Total number of iterations executed.
   iterations : u64,
+  /// Total elapsed nanoseconds across all iterations.
   total_ns   : i64,
+  /// Average nanoseconds per iteration.
   avg_ns     : i64,
+  /// Minimum nanoseconds for a single iteration.
   min_ns     : i64,
+  /// Maximum nanoseconds for a single iteration.
   max_ns     : i64
 );
 
@@ -61,7 +72,7 @@ export BenchResult;
 // bench
 // ============================================================================
 
-// Run `body` `iterations` times and return timing statistics.
+/// Run `body` for `iterations` times and return timing statistics.
 bench :: (fn(name: String, iterations: u64, body: Impl(Fn() -> unit)) -> BenchResult)({
   total_ns := i64(0);
   min_ns   := i64(9223372036854775807); // i64::MAX

package/std/thread.yo

@@ -1,38 +1,47 @@
+//! OS thread creation and management with per-thread IO event loops.
+
 extern "Yo",
-  // Thread utilities
   __yo_thread_get_hardware_threads : (fn() -> usize),
   __yo_get_thread_id : (fn() -> usize),
   __yo_get_cpu_id : (fn() -> i32)
 ;
 
-// Low-level runtime types and functions for Thread
 extern "Yo",
   __yo_thread_t : Type,
   __yo_thread_spawn : (fn(cb : Impl(Fn(using(io : IO)) -> unit, Send)) -> __yo_thread_t),
   __yo_thread_join : (fn(t : __yo_thread_t) -> unit)
 ;
 
-// High-level Thread wrapper - a simple struct (stack allocated)
+/// OS thread handle. Each spawned thread gets its own IO event loop.
 Thread :: struct(
   handle : __yo_thread_t
 );
 impl(Thread,
-  // Spawn a new OS thread running the given closure.
-  // The closure receives its own per-thread IO event loop.
+  /// Spawn a new OS thread running the given closure.
+  /// The closure receives its own per-thread IO event loop.
   spawn : (fn(cb : Impl(Fn(using(io : IO)) -> unit, Send)) -> Self)({
     raw := __yo_thread_spawn(cb);
     Self(raw)
   }),
   
-  // Wait for the thread to complete (blocking)
+  /// Block the current thread until this thread completes.
   join : (fn(self : *(Self)) -> unit)(
     __yo_thread_join(self.handle)
   )
 );
 
+/// Get the number of hardware threads (CPU cores) available.
+get_hardware_threads :: __yo_thread_get_hardware_threads;
+
+/// Get the current OS thread ID.
+get_thread_id :: __yo_get_thread_id;
+
+/// Get the current CPU core ID.
+get_cpu_id :: __yo_get_cpu_id;
+
 export
-  get_hardware_threads : __yo_thread_get_hardware_threads,
-  get_thread_id : __yo_get_thread_id,
-  get_cpu_id : __yo_get_cpu_id,
+  get_hardware_threads,
+  get_thread_id,
+  get_cpu_id,
   Thread
 ;

package/std/time/datetime.yo

@@ -1,23 +1,21 @@
-// std/time/datetime.yo - Wall-clock date/time
-//
-// DateTime represents a calendar date and time of day.
-// All values are in UTC unless utc_offset_secs is non-zero.
-//
-// Example:
-//   { DateTime } :: import "std/time/datetime";
-//
-//   now := DateTime.now_utc();
-//   println(now.to_string());   // "2026-02-26T17:41:24Z"
+//! Wall-clock date and time in UTC.
+//!
+//! # Example
+//!
+//! ```rust
+//! { DateTime } :: import "std/time/datetime";
+//!
+//! now := DateTime.now_utc();
+//! println(now.to_string());   // "2026-02-26T17:41:24Z"
+//! ```
 
 { String } :: import "../string";
 { ToString } :: import "../fmt";
 { CLOCK_REALTIME, clock_gettime } :: import "../sys/clock";
 { snprintf } :: import "../libc/stdio";
 
-// ============================================================================
-// DateTime
-// ============================================================================
-
+/// Calendar date and time with nanosecond precision.
+/// Values are in UTC unless `utc_offset_secs` is non-zero.
 DateTime :: struct(
   year            : i32,
   month           : u8,

package/std/time/duration.yo

@@ -1,22 +1,20 @@
-// std/time/duration.yo - Duration type
-//
-// Represents a span of time with nanosecond precision.
-//
-// Example:
-//   { Duration } :: import "std/time/duration";
-//
-//   d := Duration.from_millis(i64(500));
-//   println(d.as_secs());    // 0
-//   println(d.as_millis());  // 500
+//! Duration type representing a span of time with nanosecond precision.
+//!
+//! # Example
+//!
+//! ```rust
+//! { Duration } :: import "std/time/duration";
+//!
+//! d := Duration.from_millis(i64(500));
+//! println(d.as_secs());    // 0
+//! println(d.as_millis());  // 500
+//! ```
 
 { String } :: import "../string";
 { ToString } :: import "../fmt";
 { snprintf } :: import "../libc/stdio";
 
-// ============================================================================
-// Duration
-// ============================================================================
-
+/// Span of time stored as seconds and nanoseconds.
 Duration :: struct(
   secs  : i64,
   nanos : i64

package/std/time/instant.yo

@@ -1,23 +1,20 @@
-// std/time/instant.yo - Monotonic clock instant
-//
-// Instant captures a point in time from the monotonic clock.
-// Use it to measure elapsed time. Not suitable for wall-clock times.
-//
-// Example:
-//   { Instant } :: import "std/time/instant";
-//
-//   start := Instant.now();
-//   // ... do work ...
-//   elapsed := start.elapsed();
-//   println(elapsed.as_millis());
+//! Monotonic clock instant for measuring elapsed time.
+//!
+//! # Example
+//!
+//! ```rust
+//! { Instant } :: import "std/time/instant";
+//!
+//! start := Instant.now();
+//! // ... do work ...
+//! elapsed := start.elapsed();
+//! println(elapsed.as_millis());
+//! ```
 
 { Duration } :: import "./duration";
 { CLOCK_MONOTONIC, clock_gettime } :: import "../sys/clock";
 
-// ============================================================================
-// Instant - monotonic clock snapshot
-// ============================================================================
-
+/// Snapshot from the monotonic clock. Use `elapsed` to measure durations.
 Instant :: struct(
   secs  : i64,
   nanos : i64

package/std/time/sleep.yo

@@ -1,16 +1,17 @@
-// std/time/sleep.yo - Synchronous sleep
-//
-// Blocks the current thread for the given number of milliseconds.
-// For async (non-blocking) sleep, use std/sys/timer.yo instead.
-//
-// Example:
-//   { sleep } :: import "std/time/sleep";
-//   sleep(usize(100)); // sleep 100ms
+//! Synchronous sleep — blocks the current thread.
+//!
+//! # Example
+//!
+//! ```rust
+//! { sleep } :: import "std/time/sleep";
+//! sleep(usize(100)); // sleep 100ms
+//! ```
 
 extern "Yo",
   __yo_ms_sleep : (fn(ms: usize) -> unit)
 ;
 
+/// Block the current thread for the given number of milliseconds.
 sleep :: __yo_ms_sleep;
 
 export