@shd101wyy/yo 0.1.12 → 0.1.13

package/std/fs/walker.yo

@@ -1,25 +1,26 @@
-// std/fs/walker.yo - Recursive directory traversal
-//
-// Walks a directory tree and collects entries.
-//
-// Example:
-//   { walk, WalkEntry } :: import "std/fs/walker";
-//
-//   main :: (fn(using(io : IO)) -> unit)({
-//     given(exn) : Exception = {
-//       throw : (fn(forall(T : Type), error: AnyError) -> T)(
-//         { println(error.to_string()); exit(i32(1)); }
-//       )
-//     };
-//
-//     entries := io.await(walk(`/tmp`));
-//     i := usize(0);
-//     while runtime((i < entries.len())), {
-//       e := entries.get(i).unwrap();
-//       println(e.path);
-//       i = (i + usize(1));
-//     };
-//   });
+//! Recursive directory traversal.
+//!
+//! # Example
+//!
+//! ```rust
+//! { walk, WalkEntry } :: import "std/fs/walker";
+//!
+//! main :: (fn(using(io : IO)) -> unit)({
+//!   given(exn) : Exception = {
+//!     throw : (fn(forall(T : Type), error: AnyError) -> T)(
+//!       { println(error.to_string()); exit(i32(1)); }
+//!     )
+//!   };
+//!
+//!   entries := io.await(walk(`/tmp`));
+//!   i := usize(0);
+//!   while runtime((i < entries.len())), {
+//!     e := entries.get(i).unwrap();
+//!     println(e.path);
+//!     i = (i + usize(1));
+//!   };
+//! });
+//! ```
 
 { ArrayList } :: import "../collections/array_list";
 open import "../string";
@@ -30,10 +31,7 @@ open import "../string";
 { DirEntry } :: import "./dir";
 _dir :: import "./dir";
 
-// ============================================================================
-// WalkEntry
-// ============================================================================
-
+/// Entry returned by the directory walker.
 WalkEntry :: struct(
   path      : Path,
   name      : String,
@@ -43,10 +41,7 @@ WalkEntry :: struct(
 
 export WalkEntry;
 
-// ============================================================================
-// WalkOptions
-// ============================================================================
-
+/// Options controlling directory walk behavior.
 WalkOptions :: struct(
   max_depth     : ?(u32),
   follow_symlinks : bool,
@@ -147,7 +142,7 @@ walk_with_cstr :: (fn(root: *(u8), options: WalkOptions, using(io : IO)) -> Impl
   walk_with(Path.from_cstr(root), options)
 );
 
-// Walk a directory tree with default options.
+/// Walk a directory tree with default options.
 walk :: (fn(root: Path, using(io : IO)) -> Impl(Future(ArrayList(WalkEntry), IO, Exception)))
   walk_with(root, WalkOptions.defaults())
 ;

package/std/gc.yo

@@ -1,9 +1,14 @@
+//! Garbage collection interface for cycle collection.
+
 extern "Yo",
   __yo_gc_collect : (fn() -> unit),
   __yo_gc_tracked_count : (fn() -> u64)
 ;
 
+/// Trigger the cycle collector to reclaim reference cycles.
 collect :: __yo_gc_collect;
+
+/// Get the number of objects currently tracked by the cycle collector.
 tracked_count :: __yo_gc_tracked_count;
 
 export collect;

package/std/glob/index.yo

@@ -1,3 +1,5 @@
+//! Glob pattern matching for file paths.
+
 open import "../string";
 { ArrayList } :: import "../collections/array_list";
 
@@ -190,6 +192,7 @@ glob_match :: (fn(pattern: String, text: String) -> bool)(
   _glob_match_impl(pattern.as_bytes(), usize(0), text.as_bytes(), usize(0))
 );
 
+/// Compiled glob pattern that can be matched against strings.
 GlobPattern :: object(
   _pattern : String
 );

package/std/http/client.yo

@@ -1,3 +1,4 @@
+//! Async HTTP client with high-level fetch API.
 // std/http/client.yo - Async HTTP client using TCP
 //
 // Provides an async HTTP client and a high-level `fetch` function
@@ -35,13 +36,21 @@ open import "../fmt";
 // HttpError
 // ============================================================================
 
+/// HTTP client error variants.
 HttpError :: enum(
+  /// Failed to connect to the remote host.
   ConnectionFailed(msg: String),
+  /// The URL could not be parsed.
   InvalidUrl(msg: String),
+  /// The request timed out.
   Timeout,
+  /// Too many HTTP redirects.
   TooManyRedirects,
+  /// The URL scheme is not supported (only http/https).
   UnsupportedScheme(scheme: String),
+  /// The response body exceeds the size limit.
   ResponseTooLarge,
+  /// An unclassified HTTP error.
   Other(msg: String)
 );
 
@@ -67,6 +76,7 @@ export HttpError;
 // FetchOptions
 // ============================================================================
 
+/// Options for configuring an HTTP request.
 FetchOptions :: object(
   method  : HttpMethod,
   headers : ArrayList(HttpHeader),
@@ -74,6 +84,7 @@ FetchOptions :: object(
 );
 
 impl(FetchOptions,
+  /// Create default options (GET, no headers, empty body).
   new : (fn() -> Self)(
     Self(
       method: .GET,
@@ -82,16 +93,19 @@ impl(FetchOptions,
     )
   ),
 
+  /// Set the HTTP method.
   with_method : (fn(self: Self, method: HttpMethod) -> Self)({
     self.method = method;
     self
   }),
 
+  /// Add a request header.
   with_header : (fn(self: Self, name: String, value: String) -> Self)({
     self.headers.push(HttpHeader.new(name, value));
     self
   }),
 
+  /// Set the request body.
   with_body : (fn(self: Self, body: String) -> Self)({
     self.body = body;
     self
@@ -229,11 +243,11 @@ _read_http_response :: (fn(stream: TcpStream, using(io : IO, exn : Exception)) -
 // fetch — High-level async HTTP request (like JavaScript's fetch)
 // ============================================================================
 
-// Perform an HTTP request with custom options.
-//
-// Example:
-//   opts := FetchOptions.new().with_method(.POST).with_body(`{"key": "value"}`);
-//   resp := io.await(fetch_with(`http://example.com/api`, opts, using(io)));
+/// Perform an HTTP request with custom options.
+///
+/// Example:
+///   opts := FetchOptions.new().with_method(.POST).with_body(`{"key": "value"}`);
+///   resp := io.await(fetch_with(`http://example.com/api`, opts, using(io)));
 fetch_with :: (fn(url_str: String, opts: FetchOptions, using(io : IO)) ->
   Impl(Future(HttpResponse, IO, Exception))
 )(
@@ -342,12 +356,12 @@ fetch_with :: (fn(url_str: String, opts: FetchOptions, using(io : IO)) ->
 
 export fetch_with;
 
-// Perform an HTTP GET request to the given URL string.
-// Returns the HttpResponse on success.
-//
-// Example:
-//   resp := io.await(fetch(`http://example.com`, using(io)));
-//   cond(resp.is_ok() => println(resp.body), true => println(`Error`));
+/// Perform an HTTP GET request to the given URL string.
+/// Returns the `HttpResponse` on success.
+///
+/// Example:
+///   resp := io.await(fetch(`http://example.com`, using(io)));
+///   cond(resp.is_ok() => println(resp.body), true => println(`Error`));
 fetch :: (fn(url_str: String, using(io : IO)) ->
   Impl(Future(HttpResponse, IO, Exception))
 )(

package/std/http/http.yo

@@ -1,9 +1,11 @@
+//! HTTP core types — methods, headers, requests, and responses.
 // std/http/http.yo - HTTP types and request/response builders
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";
 { ToString } :: import "../fmt";
 
+/// Standard HTTP request methods.
 HttpMethod :: enum(GET, POST, PUT, DELETE, HEAD, PATCH);
 
 impl(HttpMethod, ToString(
@@ -19,14 +21,17 @@ impl(HttpMethod, ToString(
   )
 ));
 
+/// An HTTP header as a name-value pair.
 HttpHeader :: object(name: String, value: String);
 
 impl(HttpHeader,
+  /// Create a new header with the given name and value.
   new : (fn(name: String, value: String) -> Self)(
     Self(name: name, value: value)
   )
 );
 
+/// An HTTP request with method, path, headers, and optional body.
 HttpRequest :: object(
   method: HttpMethod,
   path: String,
@@ -35,32 +40,39 @@ HttpRequest :: object(
 );
 
 impl(HttpRequest,
+  /// Create a new request with the given method and path.
   new : (fn(method: HttpMethod, path: String) -> Self)(
     Self(method: method, path: path, headers: ArrayList(HttpHeader).new(), body: ``)
   ),
 
+  /// Add a header and return the request (builder pattern).
   header : (fn(self: Self, name: String, value: String) -> Self)({
     self.headers.push(HttpHeader.new(name, value));
     self
   }),
 
+  /// Set the request body and return the request (builder pattern).
   with_body : (fn(self: Self, body: String) -> Self)({
     self.body = body;
     self
   }),
 
+  /// Set the Host header.
   set_host : (fn(self: Self, host: String) -> unit)({
     self.headers.push(HttpHeader.new(`Host`, host));
   }),
 
+  /// Append a header to the request.
   set_header : (fn(self: Self, name: String, value: String) -> unit)({
     self.headers.push(HttpHeader.new(name, value));
   }),
 
+  /// Set the request body.
   set_body : (fn(self: Self, body: String) -> unit)({
     self.body = body;
   }),
 
+  /// Serialize the request to an HTTP/1.1 wire-format string.
   to_string : (fn(self: Self) -> String)({
     result := `${self.method.to_string()} ${self.path} HTTP/1.1\r\n`;
     i := usize(0);
@@ -77,6 +89,7 @@ impl(HttpRequest,
   })
 );
 
+/// An HTTP response with status code, headers, and body.
 HttpResponse :: object(
   status_code: i32,
   status_text: String,
@@ -85,10 +98,12 @@ HttpResponse :: object(
 );
 
 impl(HttpResponse,
+  /// Create a new response with the given status code and text.
   new : (fn(status_code: i32, status_text: String) -> Self)(
     Self(status_code: status_code, status_text: status_text, headers: ArrayList(HttpHeader).new(), body: ``)
   ),
 
+  /// Look up a header value by name (case-insensitive).
   get_header : (fn(self: Self, name: String) -> Option(String))({
     lower_name := name.to_lowercase();
     i := usize(0);
@@ -99,19 +114,23 @@ impl(HttpResponse,
     .None
   }),
 
+  /// Return `true` if the status code is in the 2xx range.
   is_ok : (fn(self: Self) -> bool)(
     ((self.status_code >= i32(200)) && (self.status_code < i32(300)))
   ),
 
+  /// Return `true` if the status code is in the 3xx range.
   is_redirect : (fn(self: Self) -> bool)(
     ((self.status_code >= i32(300)) && (self.status_code < i32(400)))
   ),
 
+  /// Return `true` if the status code is 4xx or higher.
   is_error : (fn(self: Self) -> bool)(
     (self.status_code >= i32(400))
   )
 );
 
+/// Parse a raw HTTP response string into an `HttpResponse`.
 parse_response :: (fn(raw: String) -> Result(HttpResponse, String))({
   lines := raw.split(`\r\n`);
   cond((lines.len() == usize(0)) => { return .Err(`Empty response`); }, true => ());
@@ -174,6 +193,7 @@ parse_response :: (fn(raw: String) -> Result(HttpResponse, String))({
   .Ok(resp)
 });
 
+/// Return the standard status text for an HTTP status code.
 http_status_text :: (fn(code: i32) -> String)(
   cond(
     (code == i32(200)) => `OK`,

package/std/http/index.yo

@@ -1,3 +1,4 @@
+//! HTTP client library — types, request building, and async fetching.
 // std/http - HTTP types, request/response builders, and async client.
 //
 // Example:

package/std/io/reader.yo

@@ -1,15 +1,11 @@
-// std/io/reader.yo - Reader trait for byte-level input
-//
-// Provides a common interface for reading bytes from various sources
-// (files, network streams, buffers, etc.)
+//! Reader trait for byte-level input.
 
 { Exception } :: import "../error";
 
-// Reader trait — synchronous byte reading interface.
-// Types implementing Reader provide `read` for reading into a buffer.
+/// Common interface for reading bytes from various sources.
 Reader :: trait(
-  // Read up to `size` bytes into buffer `buf`.
-  // Returns the number of bytes actually read (0 at end-of-stream).
+  /// Read up to `size` bytes into buffer `buf`.
+  /// Returns the number of bytes actually read (0 at end-of-stream).
   read :
     fn(self: *(Self), buf: *(u8), size: usize, using(exn : Exception)) -> usize
 );

package/std/io/writer.yo

@@ -1,17 +1,14 @@
-// std/io/writer.yo - Writer trait for byte-level output
-//
-// Provides a common interface for writing bytes to various destinations
-// (files, network streams, buffers, etc.)
+//! Writer trait for byte-level output.
 
 { Exception } :: import "../error";
 
-// Writer trait — synchronous byte writing interface.
+/// Common interface for writing bytes to a destination.
 Writer :: trait(
-  // Write bytes from buffer. Returns number of bytes written.
+  /// Write bytes from buffer. Returns number of bytes written.
   write :
     fn(self: *(Self), buf: *(u8), size: usize, using(exn : Exception)) -> usize,
 
-  // Flush any buffered data to the underlying destination.
+  /// Flush any buffered data to the underlying destination.
   flush :
     fn(self: *(Self), using(exn : Exception)) -> unit
 );

package/std/libc/assert.yo

@@ -1,5 +1,5 @@
-// C11 assert.h - Assertion debugging facility
-// Provides runtime assertion checking for debugging
+//! C11 `<assert.h>` — assertion debugging facility.
+//! Provides runtime assertion checking for debugging.
 
 c_include "<assert.h>",
   // The actual assertion function called by the assert macro

package/std/libc/ctype.yo

@@ -1,5 +1,4 @@
-// C11 ctype.h - Character classification and conversion functions
-// Provides functions to test and convert character types
+//! C11 `<ctype.h>` — character classification and conversion functions.
 
 c_include "<ctype.h>",
   // Character classification functions

package/std/libc/dirent.yo

@@ -1,5 +1,4 @@
-// C11 dirent.h - Directory entry operations
-// Provides directory traversal functionality
+//! C11 `<dirent.h>` — directory entry operations.
 
 c_include "<dirent.h>",
   // Types

package/std/libc/errno.yo

@@ -1,5 +1,4 @@
-// C11 errno.h - Error handling constants and errno variable
-// Provides standard error codes and errno global variable
+//! C11 `<errno.h>` — error handling constants and `errno` variable.
 
 c_include "<errno.h>",
   // The errno variable - global error indicator

package/std/libc/fcntl.yo

@@ -1,5 +1,5 @@
-// POSIX fcntl.h - File control options
-// Provides open flags and file control operations
+//! POSIX `<fcntl.h>` — file control options.
+//! Provides open flags and file control operations.
 
 c_include "<fcntl.h>",
   // File access modes (for open)

package/std/libc/float.yo

@@ -1,5 +1,4 @@
-// C11 float.h - Floating-point implementation limits
-// Provides implementation-defined limits for floating-point types
+//! C11 `<float.h>` — floating-point implementation limits.
 
 c_include "<float.h>",
   // Floating-point model parameters

package/std/libc/limits.yo

@@ -1,5 +1,4 @@
-// C11 limits.h - Implementation-defined limits for integer types
-// Provides minimum and maximum values for various integer types
+//! C11 `<limits.h>` — implementation-defined limits for integer types.
 
 c_include "<limits.h>",
   // Character limits

package/std/libc/math.yo

@@ -1,3 +1,5 @@
+//! C11 `<math.h>` — mathematical functions and constants.
+
 c_include "<math.h>",
   // Mathematical constants (implementation-defined)
   M_E : f64,           // e (2.71828...)

package/std/libc/signal.yo

@@ -1,5 +1,4 @@
-// C11 signal.h - Signal handling functions and constants
-// Provides signal handling capabilities for process control
+//! C11 `<signal.h>` — signal handling functions and constants.
 
 c_include "<signal.h>",
   // Signal handler type

package/std/libc/stdatomic.yo

@@ -1,5 +1,4 @@
-// C11 Atomic Operations and Types
-// Corresponds to C's <stdatomic.h>
+//! C11 `<stdatomic.h>` — atomic operations and types.
 
 c_include "<stdatomic.h>",  
   // Atomic types

package/std/libc/stdint.yo

@@ -1,6 +1,7 @@
-// C11 stdint.h - Fixed-width integer types and limits
-// Note: Yo already has i8, i16, i32, i64, u8, u16, u32, u64
-// This file provides C-compatible aliases and additional types/constants
+//! C11 `<stdint.h>` — fixed-width integer types and limits.
+//!
+//! Note: Yo already has `i8`, `i16`, `i32`, `i64`, `u8`, `u16`, `u32`, `u64`.
+//! This file provides C-compatible aliases and additional types/constants.
 
 // Type aliases for C compatibility (mapping Yo types to C stdint names)
 int8_t :: i8;

package/std/libc/stdio.yo

@@ -1,3 +1,5 @@
+//! C11 `<stdio.h>` — standard I/O functions.
+
 c_include "<stdio.h>",
   // Types
   FILE : Type,

package/std/libc/stdlib.yo

@@ -1,3 +1,5 @@
+//! C11 `<stdlib.h>` — general utility functions.
+
 c_include "<stdlib.h>",
   // Types for div functions
   div_t : Type,

package/std/libc/string.yo

@@ -1,3 +1,5 @@
+//! C11 `<string.h>` — string and memory functions.
+
 c_include "<string.h>",
   // Memory functions
   memcpy :

package/std/libc/sys/stat.yo

@@ -1,5 +1,4 @@
-// POSIX sys/stat.h - File status and mode operations
-// Provides stat, fstat, lstat, mkdir, chmod, etc.
+//! POSIX `<sys/stat.h>` — file status and mode operations.
 
 c_include "<sys/stat.h>",
   // Types

package/std/libc/time.yo

@@ -1,5 +1,5 @@
-// C11 time.h - Date and time functions
-// Provides time manipulation, formatting, and calendar functions
+//! C11 `<time.h>` — date and time functions.
+
 c_include "<time.h>",
   // Types
   time_t : Type,

package/std/libc/unistd.yo

@@ -1,3 +1,5 @@
+//! POSIX `<unistd.h>` — standard symbolic constants and types.
+
 c_include "<unistd.h>",
   // Types
   // usize : Type,

package/std/libc/wctype.yo

@@ -1,5 +1,4 @@
-// C11 wctype.h - Wide character classification and conversion functions
-// Provides functions to test and convert wide character types
+//! C11 `<wctype.h>` — wide character classification and conversion functions.
 
 { wint_t } :: import "./stdint";
 

package/std/libc/windows.yo

@@ -1,5 +1,5 @@
-// Windows-specific C API bindings
-// Only available when compiling for Windows
+//! Windows-specific C API bindings.
+//! Only available when compiling for Windows.
 
 // Windows type aliases (using Yo types that match the C types)
 DWORD :: ulong;    // unsigned long on Windows

package/std/log/index.yo

@@ -1,22 +1,10 @@
-// std/log - Structured logging
-//
-// Provides a global logger with configurable level and output destination.
-//
-// Example:
-//   { info, warn, error, set_level, Level } :: import "std/log";
-//
-//   set_level(.Info);
-//   info(String.from("application started"));
-//   warn(String.from("disk usage high"));
+//! Structured logging with configurable level and output destination.
 
 open import "../string";
 { ToString } :: import "../fmt";
-{ fwrite, stdout, stderr } :: import "../libc/stdio";
-
-// ============================================================================
-// Level
-// ============================================================================
+{ fwrite, stdout, stderr, FILE } :: import "../libc/stdio";
 
+/// Log severity level.
 Level :: enum(Trace, Debug, Info, Warn, Error);
 
 impl(Level, ToString(
@@ -33,10 +21,7 @@ impl(Level, ToString(
 
 export Level;
 
-// ============================================================================
-// LogOutput
-// ============================================================================
-
+/// Where log messages are written.
 LogOutput :: enum(
   Stderr,
   Stdout
@@ -55,13 +40,13 @@ _global_output := LogOutput.Stderr;
 // Configuration
 // ============================================================================
 
-set_level :: (fn(level: Level) -> unit)(
-  _global_level = level
-);
+set_level :: (fn(level: Level) -> unit)({
+  _global_level = level;
+});
 
-set_output :: (fn(output: LogOutput) -> unit)(
-  _global_output = output
-);
+set_output :: (fn(output: LogOutput) -> unit)({
+  _global_output = output;
+});
 
 export set_level, set_output;
 
@@ -80,7 +65,7 @@ _level_value :: (fn(l: Level) -> i32)(
 );
 
 // Write all bytes from a String to the file handle.
-_write_string :: (fn(s: String, dest: *(void)) -> unit)({
+_write_string :: (fn(s: String, dest: *(FILE)) -> unit)({
   bytes := s.as_bytes();
   cond(
     (bytes.len() > usize(0)) => {