@shd101wyy/yo 0.1.12 → 0.1.13

package/std/collections/deque.yo

@@ -1,22 +1,20 @@
-// std/collections/deque.yo - Double-ended queue (ring buffer)
-//
-// A Deque supports O(1) push/pop at both ends using a circular buffer.
-//
-// Example:
-//   { Deque } :: import "std/collections/deque";
-//
-//   d := Deque(i32).new();
-//   d.push_back(1);
-//   d.push_front(0);
-//   x := d.pop_front().unwrap();  // 0
+//! Double-ended queue (ring buffer) with O(1) push/pop at both ends.
+//!
+//! # Example
+//!
+//! ```rust
+//! { Deque } :: import "std/collections/deque";
+//!
+//! d := Deque(i32).new();
+//! d.push_back(1);
+//! d.push_front(0);
+//! x := d.pop_front().unwrap();  // 0
+//! ```
 
 { GlobalAllocator, AllocError } :: import "../allocator";
 { malloc, realloc, free } :: GlobalAllocator;
 
-// ============================================================================
-// Deque
-// ============================================================================
-
+/// Circular buffer supporting efficient push/pop at both front and back.
 Deque :: (fn(comptime(T) : Type) -> comptime(Type))(
   object(
     _buf      : ?*(T),

package/std/collections/hash_map.yo

@@ -1,59 +1,31 @@
-/**
- * HashMap - A high-performance hash map implementation using SwissTable algorithm
- * 
- * SwissTable is a state-of-the-art hash table design developed by Google for Abseil.
- * Key features:
- * - SIMD-accelerated lookup using control bytes
- * - Quadratic probing for collision resolution
- * - 7/8 max load factor for good performance
- * - Compact memory layout with metadata array
- * 
- * Memory layout:
- * - ctrl: Array of control bytes (metadata), one per bucket
- * - data: Array of key-value pairs
- * 
- * Control byte values:
- * - 0xFF (EMPTY): Bucket is empty and never used
- * - 0xFE (DELETED): Bucket was used but is now deleted
- * - 0x00-0x7F: Lower 7 bits of hash (H2 hash), indicates occupied bucket
- * 
- * Hash function splits hash into two parts:
- * - H1: Upper bits used to find bucket group
- * - H2: Lower 7 bits stored in control byte for fast SIMD comparison
- */
+//! Hash map using SwissTable algorithm with SIMD-accelerated lookup.
+
 { GlobalAllocator, AllocError } :: import "../allocator.yo";
 { malloc, calloc, realloc, free } :: GlobalAllocator;
 
-/**
- * HashMap error types
- */
+/// Error variants for HashMap operations.
 HashMapError :: enum(
+  /// Memory allocation failed.
   AllocError(error : AllocError),
+  /// The requested key was not found.
   KeyNotFound,
+  /// Capacity calculation overflowed.
   CapacityOverflow
 );
 
-/**
- * Control byte constants for SwissTable
- */
+/// Control byte for an empty bucket (never used).
 CTRL_EMPTY :: u8(255);
+/// Control byte for a deleted bucket (tombstone).
 CTRL_DELETED :: u8(254);
 
-/**
- * Default initial capacity (must be power of 2)
- */
+/// Default initial capacity (must be power of 2).
 DEFAULT_CAPACITY :: usize(16);
 
-/**
- * Maximum load factor: 7/8 = 0.875
- * We resize when: size > capacity * 7 / 8
- */
+/// Maximum load factor numerator (7/8 = 0.875). Resize when `size > capacity * 7 / 8`.
 MAX_LOAD_FACTOR_NUMERATOR :: usize(7);
 MAX_LOAD_FACTOR_DENOMINATOR :: usize(8);
 
-/**
- * Bucket - Internal structure to store key-value pairs
- */
+/// Key-value pair stored in a hash map bucket.
 Bucket :: (fn(comptime(K): Type, comptime(V): Type) -> comptime(Type))
   struct(
     key : K,
@@ -61,29 +33,18 @@ Bucket :: (fn(comptime(K): Type, comptime(V): Type) -> comptime(Type))
   )
 ;
 
-/**
- * Extract H2 hash (lower 7 bits) from full hash
- */
+/// Extract H2 hash (lower 7 bits) from full hash for control byte comparison.
 h2_hash :: (fn(hash: u64) -> u8)
   u8(hash & u64(127))
 ;
 
-/**
- * Extract H1 hash (upper bits) for bucket index
- */
+/// Extract H1 hash (upper bits) for bucket index calculation.
 h1_hash :: (fn(hash: u64, capacity: usize) -> usize)
   (usize((hash >> u64(7))) % capacity)
 ;
 
-/**
- * HashMap type - high-performance hash table using SwissTable
- * 
- * Memory layout:
- * - ctrl: Pointer to control bytes array (length = capacity)
- * - data: Pointer to buckets array (length = capacity)
- * - capacity: Total number of buckets (always power of 2)
- * - size: Current number of occupied buckets
- */
+/// High-performance hash map using SwissTable algorithm.
+/// Keys must implement `Eq` and `Hash`. Provides O(1) average lookup, insert, and delete.
 HashMap :: (fn(
   comptime(K): Type,
   comptime(V): Type,

package/std/collections/hash_set.yo

@@ -1,78 +1,42 @@
-/**
- * HashSet - A high-performance hash set implementation using SwissTable algorithm
- * 
- * This implementation uses the same SwissTable design as HashMap, providing:
- * - SIMD-accelerated lookup using control bytes
- * - Quadratic probing for collision resolution
- * - 7/8 max load factor for optimal performance
- * - Compact memory layout with metadata array
- * 
- * Memory layout:
- * - ctrl: Array of control bytes (metadata), one per slot
- * - data: Array of elements
- * 
- * Control byte values:
- * - 0xFF (EMPTY): Slot is empty and never used
- * - 0xFE (DELETED): Slot was used but is now deleted
- * - 0x00-0x7F: Lower 7 bits of hash (H2 hash), indicates occupied slot
- * 
- * Hash function splits hash into two parts:
- * - H1: Upper bits used to find slot group
- * - H2: Lower 7 bits stored in control byte for fast SIMD comparison
- */
+//! Hash set using SwissTable algorithm with set-theoretic operations.
+
 { GlobalAllocator, AllocError } :: import "../allocator.yo";
 { malloc, calloc, realloc, free } :: GlobalAllocator;
 
-/**
- * HashSet error types
- */
+/// Error variants for HashSet operations.
 HashSetError :: enum(
+  /// Memory allocation failed.
   AllocError(error : AllocError),
+  /// The element was not found in the set.
   ElementNotFound,
+  /// Capacity calculation overflowed.
   CapacityOverflow
 );
 
-/**
- * Control byte constants for SwissTable
- */
+/// Control byte for an empty slot.
 CTRL_EMPTY :: u8(255);
+/// Control byte for a deleted slot (tombstone).
 CTRL_DELETED :: u8(254);
 
-/**
- * Default initial capacity (must be power of 2)
- */
+/// Default initial capacity (must be power of 2).
 DEFAULT_CAPACITY :: usize(16);
 
-/**
- * Maximum load factor: 7/8 = 0.875
- * We resize when: size > capacity * 7 / 8
- */
+/// Maximum load factor numerator (7/8 = 0.875).
 MAX_LOAD_FACTOR_NUMERATOR :: usize(7);
 MAX_LOAD_FACTOR_DENOMINATOR :: usize(8);
 
-/**
- * Extract H2 hash (lower 7 bits) from full hash
- */
+/// Extract H2 hash (lower 7 bits) from full hash.
 h2_hash :: (fn(hash: u64) -> u8)
   (u8((hash & u64(127))))
 ;
 
-/**
- * Extract H1 hash (upper bits) for slot index
- */
+/// Extract H1 hash (upper bits) for slot index.
 h1_hash :: (fn(hash: u64, capacity: usize) -> usize)
   ((usize((hash >> u64(7))) % capacity))
 ;
 
-/**
- * HashSet type - high-performance set using SwissTable
- * 
- * Memory layout:
- * - ctrl: Pointer to control bytes array (length = capacity)
- * - data: Pointer to elements array (length = capacity)
- * - capacity: Total number of slots (always power of 2)
- * - size: Current number of occupied slots
- */
+/// High-performance hash set using SwissTable algorithm.
+/// Elements must implement `Eq` and `Hash`. Provides O(1) average lookup and insert.
 HashSet :: (fn(
   comptime(T): Type,
   where(T <: (Eq(T), Hash))

package/std/collections/linked_list.yo

@@ -1,29 +1,14 @@
-/**
- * LinkedList - A doubly-linked list implementation for Yo language
- * 
- * Features:
- * - O(1) push/pop from front and back
- * - O(1) insertion/removal at known positions (with node reference)
- * - RAII for automatic cleanup
- * - True linked list using object indirection
- * 
- * Memory layout:
- * - Each node is an object (reference-counted)
- * - Nodes contain: value, optional next node, optional prev node
- */
+//! Doubly-linked list with O(1) push/pop at both ends.
 
-/**
- * LinkedList error types
- */
+/// Error variants for LinkedList operations.
 LinkedListError :: enum(
+  /// Index is out of bounds for the current length.
   IndexOutOfBounds(index: usize, length: usize),
+  /// Attempted to access an element from an empty list.
   EmptyList
 );
 
-/**
- * Node - Internal structure for linked list nodes
- * Since Node is an object (reference-counted), no Box needed
- */
+/// Internal node for the linked list. Reference-counted via `object`.
 Node :: (fn(comptime(T): Type) -> comptime(Type))
   object(
     value : T,
@@ -32,9 +17,7 @@ Node :: (fn(comptime(T): Type) -> comptime(Type))
   )
 ;
 
-/**
- * LinkedList - Doubly-linked list with O(1) operations at both ends
- */
+/// Doubly-linked list with O(1) push/pop at both ends.
 LinkedList :: (fn(comptime(T): Type) -> comptime(Type))
   object(
     head : Option(Node(T)),

package/std/collections/priority_queue.yo

@@ -1,23 +1,21 @@
-// std/collections/priority_queue.yo - Binary min-heap (priority queue)
-//
-// PriorityQueue keeps elements in ascending order (smallest first).
-// Use a negated key to get a max-heap.
-//
-// Example:
-//   { PriorityQueue } :: import "std/collections/priority_queue";
-//
-//   pq := PriorityQueue(i32).new();
-//   pq.push(5);
-//   pq.push(1);
-//   pq.push(3);
-//   x := pq.pop().unwrap();  // 1
+//! Binary min-heap priority queue.
+//!
+//! # Example
+//!
+//! ```rust
+//! { PriorityQueue } :: import "std/collections/priority_queue";
+//!
+//! pq := PriorityQueue(i32).new();
+//! pq.push(5);
+//! pq.push(1);
+//! pq.push(3);
+//! x := pq.pop().unwrap();  // 1
+//! ```
 
 { ArrayList } :: import "./array_list";
 
-// ============================================================================
-// PriorityQueue — min-heap backed by ArrayList
-// ============================================================================
-
+/// Min-heap backed by an ArrayList.
+/// Elements are ordered ascending (smallest first). Negate keys for max-heap behavior.
 PriorityQueue :: (fn(comptime(T) : Type) -> comptime(Type))(
   object(
     _data : ArrayList(T)

package/std/crypto/md5.yo

@@ -1,12 +1,13 @@
-// std/crypto/md5.yo - MD5 hash function
-//
-// Pure-Yo implementation of MD5 (RFC 1321).
-// MD5 is considered cryptographically broken — use SHA-256 for security.
-//
-// Example:
-//   { md5_hex } :: import "std/crypto/md5";
-//
-//   digest := md5_hex(data);  // "5d41402abc4b2a76b9719d911017c592"
+//! MD5 hash function (RFC 1321), pure Yo implementation.
+//! MD5 is considered cryptographically broken — use SHA-256 for security.
+//!
+//! # Example
+//!
+//! ```rust
+//! { md5_hex } :: import "std/crypto/md5";
+//!
+//! digest := md5_hex(data);  // "5d41402abc4b2a76b9719d911017c592"
+//! ```
 
 { ArrayList } :: import "../collections/array_list";
 { hex_encode } :: import "../encoding/hex";

package/std/crypto/random.yo

@@ -1,15 +1,14 @@
-// std/crypto/random.yo - Cryptographically secure random number generation
-//
-// Uses OS entropy sources:
-//   Linux/others: getrandom()
-//   macOS:        arc4random_buf()
-//   Windows:      BCryptGenRandom()
-//   WASI/WASM:    getentropy()
-//
-// Example:
-//   { random_u64, uuid_v4 } :: import "std/crypto/random";
-//
-//   id := uuid_v4();  // "550e8400-e29b-41d4-a716-446655440000"
+//! Cryptographically secure random number generation.
+//! Uses OS entropy sources (getrandom on Linux, arc4random_buf on macOS,
+//! BCryptGenRandom on Windows, getentropy on WASI).
+//!
+//! # Example
+//!
+//! ```rust
+//! { random_u64, uuid_v4 } :: import "std/crypto/random";
+//!
+//! id := uuid_v4();  // "550e8400-e29b-41d4-a716-446655440000"
+//! ```
 
 { ArrayList } :: import "../collections/array_list";
 { platform, Platform } :: import "../process";
@@ -23,8 +22,11 @@ open import "../string";
 // Error type
 // ============================================================================
 
+/// Errors that can occur during cryptographic random operations.
 CryptoError :: enum(
+  /// Platform does not support secure random generation.
   Unavailable,
+  /// Other platform-specific error.
   Other(msg: String)
 );
 

package/std/crypto/sha256.yo

@@ -1,11 +1,12 @@
-// std/crypto/sha256.yo - SHA-256 hash function
-//
-// Pure-Yo implementation of SHA-256 (FIPS 180-4).
-//
-// Example:
-//   { sha256_hex } :: import "std/crypto/sha256";
-//
-//   digest := sha256_hex(data);  // "2cf24dba..."
+//! SHA-256 hash function (FIPS 180-4), pure Yo implementation.
+//!
+//! # Example
+//!
+//! ```rust
+//! { sha256_hex } :: import "std/crypto/sha256";
+//!
+//! digest := sha256_hex(data);  // "2cf24dba..."
+//! ```
 
 { ArrayList } :: import "../collections/array_list";
 { hex_encode } :: import "../encoding/hex";

package/std/encoding/base64.yo

@@ -1,12 +1,10 @@
-// std/encoding/base64.yo - Base64 encoding/decoding
-//
-// Standard (RFC 4648) and URL-safe base64 variants.
-//
-// Example:
-//   { base64_encode, base64_decode } :: import "std/encoding/base64";
-//
-//   s := base64_encode(data);
-//   b := base64_decode(s.to_str()).unwrap();
+//! Base64 encoding and decoding (RFC 4648) with standard and URL-safe variants.
+//!
+//! Example:
+//!   { base64_encode, base64_decode } :: import "std/encoding/base64";
+//!
+//!   s := base64_encode(data);
+//!   b := base64_decode(s.to_str()).unwrap();
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";
@@ -58,12 +56,12 @@ _encode_with :: (fn(data: ArrayList(u8), alpha: str, pad: bool) -> String)({
   String.from_bytes(out)
 });
 
-// Encode bytes as standard base64.
+/// Encode bytes as standard base64 with padding.
 base64_encode :: (fn(data: ArrayList(u8)) -> String)(
   _encode_with(data, _STD_ALPHA, true)
 );
 
-// Encode bytes as URL-safe base64 (no padding).
+/// Encode bytes as URL-safe base64 without padding.
 base64_encode_url :: (fn(data: ArrayList(u8)) -> String)(
   _encode_with(data, _URL_ALPHA, false)
 );
@@ -116,12 +114,12 @@ _decode_with :: (fn(s: str, alpha: str, using(exn : Exception)) -> ArrayList(u8)
   out
 });
 
-// Decode standard base64.
+/// Decode a standard base64 string to bytes. Throws via `Exception` on invalid input.
 base64_decode :: (fn(s: str, using(exn : Exception)) -> ArrayList(u8))(
   _decode_with(s, _STD_ALPHA)
 );
 
-// Decode URL-safe base64.
+/// Decode a URL-safe base64 string to bytes. Throws via `Exception` on invalid input.
 base64_decode_url :: (fn(s: str, using(exn : Exception)) -> ArrayList(u8))(
   _decode_with(s, _URL_ALPHA)
 );
@@ -132,7 +130,7 @@ export base64_decode, base64_decode_url;
 // String-level convenience API
 // ============================================================================
 
-// Encode a String to standard base64.
+/// Encode a `String` to standard base64.
 base64_encode_string :: (fn(input: String) -> String)(
   _encode_with(input.as_bytes(), _STD_ALPHA, true)
 );
@@ -150,7 +148,7 @@ _base64_index :: (fn(c: u8) -> i32)({
   i32(-1)
 });
 
-// Decode a base64 String, ignoring whitespace. Returns Result.
+/// Decode a base64 `String`, ignoring whitespace. Returns `Result(String, String)`.
 base64_decode_string :: (fn(input: String) -> Result(String, String))({
   raw := input.as_str();
   cleaned := ArrayList(u8).new();

package/std/encoding/hex.yo

@@ -1,12 +1,12 @@
-// std/encoding/hex.yo - Hexadecimal encoding/decoding
-//
-// Converts between raw bytes (ArrayList(u8)) and hex strings.
-//
-// Example:
-//   { hex_encode, hex_decode } :: import "std/encoding/hex";
-//
-//   s := hex_encode(data);         // "deadbeef"
-//   b := hex_decode("deadbeef");
+//! Hexadecimal encoding and decoding.
+//!
+//! Converts between raw bytes (`ArrayList(u8)`) and hex strings.
+//!
+//! Example:
+//!   { hex_encode, hex_decode } :: import "std/encoding/hex";
+//!
+//!   s := hex_encode(data);         // "deadbeef"
+//!   b := hex_decode("deadbeef");
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";
@@ -17,8 +17,11 @@ open import "../string";
 // Error type
 // ============================================================================
 
+/// Encoding/decoding error type.
 EncodingError :: enum(
+  /// Invalid character encountered during decoding.
   InvalidChar(ch: u8),
+  /// Input string has odd length (hex requires even length).
   OddLength
 );
 
@@ -55,6 +58,7 @@ _hex_encode_impl :: (fn(data: ArrayList(u8), hex_chars: str) -> String)({
   String.from_bytes(out)
 });
 
+/// Encode bytes as a lowercase hexadecimal string.
 hex_encode :: (fn(data: ArrayList(u8)) -> String)(
   _hex_encode_impl(data, _HEX_CHARS)
 );
@@ -74,7 +78,7 @@ _hex_nibble :: (fn(c: u8, using(exn : Exception)) -> u8)(
   )
 );
 
-// Decode a hexadecimal string into bytes.
+/// Decode a hexadecimal string to bytes. Throws via `Exception` on invalid input.
 hex_decode :: (fn(s: str, using(exn : Exception)) -> ArrayList(u8))({
   cond(
     (((s.len() % usize(2)) != usize(0))) => {

package/std/encoding/html.yo

@@ -1,13 +1,13 @@
-// HTML entity decoding
-//
-// Decodes named (&), decimal (&), and hex (&) HTML character references.
-// Uses Legacy mode — entities without trailing semicolon are also decoded.
-//
-// Example:
-//   { decode_html } :: import "std/encoding/html";
-//
-//   result := decode_html(`& < & &`);
-//   assert((result == `& < & &`), "decoded entities");
+//! HTML entity decoding — named, decimal, and hexadecimal character references.
+//!
+//! Decodes named (&amp;), decimal (&#38;), and hex (&#x26;) HTML character references.
+//! Uses Legacy mode — entities without trailing semicolon are also decoded.
+//!
+//! Example:
+//!   { decode_html } :: import "std/encoding/html";
+//!
+//!   result := decode_html(`&amp; &lt; &#38; &#x26;`);
+//!   assert((result == `& < & &`), "decoded entities");
 
 open import "../string";
 { HashMap } :: import "../collections/hash_map";
@@ -64,7 +64,10 @@ _is_alpha_numeric :: (fn(c: rune) -> bool)(
   ((((c >= rune(u32('a'))) && (c <= rune(u32('z')))) || ((c >= rune(u32('A'))) && (c <= rune(u32('Z'))))) || ((c >= rune(u32('0'))) && (c <= rune(u32('9')))))
 );
 
-// Decode HTML entities in a string (Legacy mode — entities without ; are also decoded).
+/// Decode HTML entities in a string.
+///
+/// Supports named (`&amp;`), decimal (`&#38;`), and hexadecimal (`&#x26;`) character
+/// references. Legacy mode — entities without trailing semicolons are also decoded.
 decode_html :: (fn(input: String) -> String)({
   _ensure_init();
 

package/std/encoding/html_char_utils.yo

@@ -1,16 +1,19 @@
-// HTML character utility functions
-//
-// Provides Unicode codepoint validation and conversion for HTML entity processing.
-//
-// Example:
-//   { is_valid_entity_code, from_code_point } :: import "std/encoding/html_char_utils";
-//
-//   assert(is_valid_entity_code(i32(65)), "A is valid");
-//   s := from_code_point(i32(65));  // "A"
+//! HTML character utility functions.
+//!
+//! Provides Unicode codepoint validation and conversion for HTML entity processing.
+//!
+//! # Example
+//!
+//! ```rust
+//! { is_valid_entity_code, from_code_point } :: import "std/encoding/html_char_utils";
+//!
+//! assert(is_valid_entity_code(i32(65)), "A is valid");
+//! s := from_code_point(i32(65));  // "A"
+//! ```
 
 open import "../string";
 
-// Check if a Unicode codepoint is a valid HTML entity value.
+/// Check if a Unicode codepoint is a valid HTML entity value.
 is_valid_entity_code :: (fn(c: i32) -> bool)(
   cond(
     ((c >= i32(0xD800)) && (c <= i32(0xDFFF))) => false,
@@ -25,7 +28,7 @@ is_valid_entity_code :: (fn(c: i32) -> bool)(
   )
 );
 
-// Convert a Unicode codepoint to a String.
+/// Convert a Unicode codepoint to a `String`.
 from_code_point :: (fn(c: i32) -> String)(
   {
     (r : rune) = rune(u32(c));

package/std/encoding/html_entities.yo

@@ -1,17 +1,16 @@
-// HTML5 named character references data
-//
-// Auto-generated from https://html.spec.whatwg.org/entities.json
-// Total: 2125 entities
-//
-// This module provides the entity name-to-string mapping used by decode_html.
-// Import: { _build_entity_map, _build_legacy_set } :: import "std/encoding/html_entities";
+//! HTML5 named character references data.
+//!
+//! Auto-generated from <https://html.spec.whatwg.org/entities.json>.
+//! Total: 2125 entities.
+//!
+//! This module provides the entity name-to-string mapping used by `decode_html`.
 
 open import "../string";
 { HashMap } :: import "../collections/hash_map";
 { HashSet } :: import "../collections/hash_set";
 { from_code_point } :: import "./html_char_utils";
 
-// Returns a HashMap mapping entity names (without & and ;) to decoded strings.
+/// Returns a `HashMap` mapping entity names (without `&` and `;`) to decoded strings.
 _build_entity_map :: (fn() -> HashMap(String, String))(
   {
     (m : HashMap(String, String)) = HashMap(String, String).new();