@shd101wyy/yo 0.1.12 → 0.1.14

package/std/encoding/json.yo

@@ -1,14 +1,17 @@
-// std/encoding/json.yo - JSON parsing and serialisation
-//
-// Provides a dynamically-typed JSON value tree.
-//
-// Example:
-//   { json_parse, json_stringify, JsonValue } :: import "std/encoding/json";
-//   { Exception } :: import "std/error";
-//
-//   given(exn) := Exception(throw : ((err) -> { escape (); }));
-//   v := json_parse(`{"x": 1}`);
-//   println(json_stringify(v));
+//! JSON parsing and serialization.
+//!
+//! Provides a dynamically-typed JSON value tree.
+//!
+//! # Example
+//!
+//! ```rust
+//! { json_parse, json_stringify, JsonValue } :: import "std/encoding/json";
+//! { Exception } :: import "std/error";
+//!
+//! given(exn) := Exception(throw : ((err) -> { escape (); }));
+//! v := json_parse(`{"x": 1}`);
+//! println(json_stringify(v));
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";
@@ -20,12 +23,19 @@ open import "../string";
 // JsonError
 // ============================================================================
 
+/// JSON parsing error type.
 JsonError :: enum(
+  /// Encountered an unexpected character at the given position.
   UnexpectedChar(ch: u8, pos: usize),
+  /// Input ended unexpectedly.
   UnexpectedEnd,
+  /// Failed to parse a numeric literal.
   InvalidNumber,
+  /// Invalid escape sequence in a string.
   InvalidEscape,
+  /// Invalid Unicode escape in a string.
   InvalidUnicode,
+  /// Other error with a descriptive message.
   Other(msg: String)
 );
 
@@ -50,12 +60,19 @@ export JsonError;
 // JsonValue
 // ============================================================================
 
+/// Dynamically-typed JSON value tree.
 JsonValue :: enum(
+  /// JSON null.
   Null,
+  /// JSON boolean.
   Bool(value: bool),
+  /// JSON number (IEEE 754 double).
   Number(value: f64),
+  /// JSON string.
   Str(value: String),
+  /// JSON array of values.
   Array(items: ArrayList(Self)),
+  /// JSON object with ordered key-value pairs.
   Object(keys: ArrayList(String), values: ArrayList(Self))
 );
 
@@ -63,13 +80,14 @@ JsonValue :: enum(
 // JsonKV - key/value pair convenience struct for Object
 // ============================================================================
 
+/// Key-value pair for JSON object entries.
 JsonKV :: struct(
   key   : String,
   value : JsonValue
 );
 
 impl(JsonValue,
-  // Get a field from an Object value. Returns .None if not an Object or key missing.
+  /// Get a field from an Object value by key. Returns `.None` if not an Object or key is missing.
   get : (fn(self: Self, key: String) -> Option(JsonValue))(
     match(self,
       .Object(keys, values) => {
@@ -88,7 +106,7 @@ impl(JsonValue,
     )
   ),
 
-  // Get an element from an Array value by index.
+  /// Get an element from an Array value by index.
   at : (fn(self: Self, index: usize) -> Option(JsonValue))(
     match(self,
       .Array(items) => items.get(index),
@@ -96,7 +114,7 @@ impl(JsonValue,
     )
   ),
 
-  // Extract a bool.
+  /// Extract the boolean value, or `.None` if not a `Bool`.
   as_bool : (fn(self: Self) -> Option(bool))(
     match(self,
       .Bool(b) => .Some(b),
@@ -104,7 +122,7 @@ impl(JsonValue,
     )
   ),
 
-  // Extract a number.
+  /// Extract the numeric value, or `.None` if not a `Number`.
   as_number : (fn(self: Self) -> Option(f64))(
     match(self,
       .Number(n) => .Some(n),
@@ -112,7 +130,7 @@ impl(JsonValue,
     )
   ),
 
-  // Extract a string.
+  /// Extract the string value, or `.None` if not a `Str`.
   as_string : (fn(self: Self) -> Option(String))(
     match(self,
       .Str(s) => .Some(s),
@@ -120,7 +138,7 @@ impl(JsonValue,
     )
   ),
 
-  // Extract an array.
+  /// Extract the array items, or `.None` if not an `Array`.
   as_array : (fn(self: Self) -> Option(ArrayList(JsonValue)))(
     match(self,
       .Array(items) => .Some(items),
@@ -128,7 +146,7 @@ impl(JsonValue,
     )
   ),
 
-  // Extract object entries as ArrayList(JsonKV).
+  /// Extract object entries as `ArrayList(JsonKV)`, or `.None` if not an `Object`.
   as_object : (fn(self: Self) -> Option(ArrayList(JsonKV)))(
     match(self,
       .Object(keys, values) => {
@@ -468,6 +486,7 @@ _parse_value :: (fn(p: _Parser) -> Result(JsonValue, JsonError))({
 // Public API
 // ============================================================================
 
+/// Parse a JSON string into a `JsonValue` tree. Throws via `Exception` on invalid input.
 json_parse :: (fn(s: str, using(exn : Exception)) -> JsonValue)({
   p := _Parser.new(s);
   match(_parse_value(p),
@@ -558,13 +577,14 @@ _stringify_into :: (fn(value: JsonValue, out: ArrayList(u8)) -> unit)({
   );
 });
 
+/// Serialize a `JsonValue` to a compact JSON string.
 json_stringify :: (fn(value: JsonValue) -> String)({
   out := ArrayList(u8).new();
   _stringify_into(value, out);
   String.from_bytes(out)
 });
 
-// Serialise with pretty-printing (delegates to compact for now).
+/// Serialize a `JsonValue` to a pretty-printed JSON string.
 json_stringify_pretty :: (fn(value: JsonValue, _indent: usize) -> String)(
   json_stringify(value)
 );

package/std/encoding/punycode.yo

@@ -1,14 +1,17 @@
-// Punycode codec (RFC 3492)
-//
-// Provides punycode encoding/decoding and IDN hostname conversion.
-//
-// Example:
-//   { punycode_decode, punycode_encode, to_unicode, to_ascii } :: import "std/encoding/punycode";
-//
-//   encoded := punycode_encode(`München`);
-//   decoded := punycode_decode(encoded);
-//   ascii_domain := to_ascii(`münchen.de`);  // "xn--mnchen-3ya.de"
-//   unicode_domain := to_unicode(ascii_domain);  // "münchen.de"
+//! Punycode encoding/decoding (RFC 3492) for internationalized domain names.
+//!
+//! Provides punycode encoding/decoding and IDN hostname conversion.
+//!
+//! # Example
+//!
+//! ```rust
+//! { punycode_decode, punycode_encode, to_unicode, to_ascii } :: import "std/encoding/punycode";
+//!
+//! encoded := punycode_encode(`München`);
+//! decoded := punycode_decode(encoded);
+//! ascii_domain := to_ascii(`münchen.de`);  // "xn--mnchen-3ya.de"
+//! unicode_domain := to_unicode(ascii_domain);  // "münchen.de"
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";
@@ -122,8 +125,9 @@ _string_to_codepoints :: (fn(s: String) -> ArrayList(i32))({
   cps
 });
 
-// Decode a punycode-encoded string (without the xn-- prefix).
-// Returns .Some(decoded) on success, .None on error.
+/// Decode a punycode-encoded string (without the `xn--` prefix).
+///
+/// Returns `.Some(decoded)` on success, `.None` on invalid input.
 punycode_decode :: (fn(input: String) -> Option(String))({
   (bytes : ArrayList(u8)) = input.as_bytes();
   (input_len : i32) = i32(bytes.len());
@@ -220,7 +224,7 @@ punycode_decode :: (fn(input: String) -> Option(String))({
   .Some(String.from_bytes(result_bytes))
 });
 
-// Encode a Unicode string to punycode (without the xn-- prefix).
+/// Encode a Unicode string to punycode (without the `xn--` prefix).
 punycode_encode :: (fn(input: String) -> String)({
   (cps : ArrayList(i32)) = _string_to_codepoints(input);
   (cp_count : i32) = i32(cps.len());
@@ -300,8 +304,9 @@ punycode_encode :: (fn(input: String) -> String)({
   String.from_bytes(out)
 });
 
-// Convert an IDN hostname to Unicode display form.
-// Splits on '.', decodes xn-- labels, keeps original on failure.
+/// Convert an IDN hostname to Unicode display form.
+///
+/// Splits on `.`, decodes `xn--` labels via punycode, and keeps original labels on failure.
 to_unicode :: (fn(hostname: String) -> String)({
   (parts : ArrayList(String)) = hostname.split(`.`);
   (result : String) = ``;
@@ -331,8 +336,9 @@ to_unicode :: (fn(hostname: String) -> String)({
   result
 });
 
-// Convert a Unicode hostname to ASCII punycode form.
-// Non-ASCII labels get xn-- prefix.
+/// Convert a Unicode hostname to ASCII-compatible encoding.
+///
+/// Non-ASCII labels are punycode-encoded with the `xn--` prefix.
 to_ascii :: (fn(hostname: String) -> String)({
   (parts : ArrayList(String)) = hostname.split(`.`);
   (result : String) = ``;

package/std/encoding/toml.yo

@@ -1,28 +1,38 @@
-// std/encoding/toml.yo - Basic TOML parser
-//
-// Parses a subset of TOML into a TomlValue tree.
-// Supports: strings, integers, booleans, table sections, comments.
-//
-// Example:
-//   { toml_parse, TomlValue } :: import "std/encoding/toml";
-//   // Or via the encoding index:
-//   { toml_parse, TomlValue } :: import "std/encoding";
+//! Basic TOML parser for configuration files.
+//!
+//! Parses a subset of TOML into a `TomlValue` tree.
+//! Supports: strings, integers, booleans, table sections, comments.
+//!
+//! # Example
+//!
+//! ```rust
+//! { toml_parse, TomlValue } :: import "std/encoding/toml";
+//! // Or via the encoding index:
+//! { toml_parse, TomlValue } :: import "std/encoding";
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";
 
+/// TOML value type — the result of parsing a TOML document.
 TomlValue :: enum(
+  /// A TOML string value.
   Str(value: String),
+  /// A TOML integer value.
   Int(value: i64),
+  /// A TOML boolean value.
   Bool(value: bool),
+  /// A TOML table (ordered key-value map).
   Table(keys: ArrayList(String), values: ArrayList(Self))
 );
 
 impl(TomlValue,
+  /// Create a new empty table.
   new_table : (fn() -> Self)(
     Self.Table(keys: ArrayList(String).new(), values: ArrayList(TomlValue).new())
   ),
 
+  /// Look up a value by key in a table. Returns `.None` if not a table or key is missing.
   get : (fn(self: Self, key: String) -> Option(TomlValue))(
     match(self,
       .Table(keys, values) => {
@@ -41,10 +51,12 @@ impl(TomlValue,
     )
   ),
 
+  /// Check whether the table contains the given key.
   has_key : (fn(self: Self, key: String) -> bool)(
     self.get(key).is_some()
   ),
 
+  /// Insert or update a key-value pair in the table.
   set : (fn(self: Self, key: String, value: TomlValue) -> unit)(
     match(self,
       .Table(keys, values) => {
@@ -72,6 +84,7 @@ impl(TomlValue,
     )
   ),
 
+  /// Return the number of keys in the table, or `0` if not a table.
   table_len : (fn(self: Self) -> usize)(
     match(self,
       .Table(keys, _) => keys.len(),
@@ -79,14 +92,17 @@ impl(TomlValue,
     )
   ),
 
+  /// Extract the string value, or `.None` if not a `Str`.
   as_string : (fn(self: Self) -> Option(String))(
     match(self, .Str(s) => .Some(s), _ => .None)
   ),
 
+  /// Extract the integer value, or `.None` if not an `Int`.
   as_int : (fn(self: Self) -> Option(i64))(
     match(self, .Int(n) => .Some(n), _ => .None)
   ),
 
+  /// Extract the boolean value, or `.None` if not a `Bool`.
   as_bool : (fn(self: Self) -> Option(bool))(
     match(self, .Bool(b) => .Some(b), _ => .None)
   )
@@ -129,6 +145,7 @@ _parse_toml_value :: (fn(raw: String) -> Result(TomlValue, String))({
   .Err(`Unknown value: ${trimmed}`)
 });
 
+/// Parse a TOML string into a `TomlValue` tree. Returns `Result(TomlValue, String)`.
 toml_parse :: (fn(input: String) -> Result(TomlValue, String))({
   root_keys := ArrayList(String).new();
   root_vals := ArrayList(TomlValue).new();

package/std/encoding/utf16.yo

@@ -1,12 +1,15 @@
-// std/encoding/utf16.yo - UTF-8 <-> UTF-16 conversion
-//
-// Converts between Yo's UTF-8 String and UTF-16LE/BE (as ArrayList(u16)).
-//
-// Example:
-//   { utf8_to_utf16, utf16_to_utf8 } :: import "std/encoding/utf16";
-//
-//   words := utf8_to_utf16("hello");
-//   s := utf16_to_utf8(words);
+//! UTF-8 to UTF-16 conversion and vice versa.
+//!
+//! Converts between Yo's UTF-8 `str` and UTF-16 code units (`ArrayList(u16)`).
+//!
+//! # Example
+//!
+//! ```rust
+//! { utf8_to_utf16, utf16_to_utf8 } :: import "std/encoding/utf16";
+//!
+//! words := utf8_to_utf16("hello");
+//! s := utf16_to_utf8(words);
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";
@@ -17,6 +20,9 @@ open import "../string";
 // UTF-8 → UTF-16
 // ============================================================================
 
+/// Convert a UTF-8 string to an `ArrayList(u16)` of UTF-16 code units.
+///
+/// Handles BMP characters directly and encodes supplementary characters as surrogate pairs.
 utf8_to_utf16 :: (fn(s: str) -> ArrayList(u16))({
   out := ArrayList(u16).new();
   i   := usize(0);
@@ -64,6 +70,10 @@ export utf8_to_utf16;
 // UTF-16 → UTF-8
 // ============================================================================
 
+/// Convert UTF-16 code units to a UTF-8 `String`.
+///
+/// Decodes surrogate pairs back into supplementary code points.
+/// Throws via `Exception` on unpaired surrogates.
 utf16_to_utf8 :: (fn(data: ArrayList(u16), using(exn : Exception)) -> String)({
   out := ArrayList(u8).new();
   i   := usize(0);

package/std/error.yo

@@ -1,14 +1,10 @@
-// std/error.yo - Error trait
-//
-// Provides a standard Error trait for typed error propagation.
-// All error types in the standard library should implement this trait.
+//! Standard error handling types and traits for Yo.
+
 open import "./string";
 open import "./fmt";
 
-// ============================================================================
-// Error trait
-// ============================================================================
-
+/// Standard error trait for typed error propagation.
+/// All error types should implement this trait along with `ToString`.
 Error :: trait(
   (source : (fn(self: *(Self)) -> Option(Dyn(SelfTrait)))) ?= ((self) -> .None),
 
@@ -16,32 +12,23 @@ Error :: trait(
 );
 export Error;
 
+/// Type-erased dynamic error type. Wraps any type implementing `Error`.
 AnyError :: Dyn(Error);
 export AnyError;
 
-// ============================================================================
-// Error implementations for standard types
-// ============================================================================
-
+/// Allows using `String` directly as an error type.
 impl(String, Error());
 
-/// === Exception ===
-// This is a non-resumable exception handling.  
-// 
-// Example (function that may throw):
-//
-//   safe_div :: (fn(x: i32, y: i32, using(exn : Exception)) -> i32)(
-//     cond(
-//       (y == i32(0)) => exn.throw(dyn `division by zero`)),
-//       true => (x / y)
-//     )
-//   );
+/// Non-resumable exception handling effect module.
+/// Use `throw` to raise an `AnyError` and abort the current computation.
 Exception :: module(
   throw : (fn(forall(ResumeType : Type), error : AnyError) -> ResumeType)
 );
 export Exception;
 
 
+/// Creates a resumable exception module parameterized by the resume type.
+/// Unlike `Exception`, the handler can return a value to resume the computation.
 ResumableException :: (fn(comptime(ResumeType) : Type) -> comptime(Module))(
   module(
     throw : (fn(error : AnyError) -> ResumeType)

package/std/fmt/display.yo

@@ -1,25 +1,23 @@
-// std/fmt/display.yo - Display trait
-//
-// The Display trait provides a standard way to format a value for
-// human-readable output using a Writer. It complements ToString
-// (which always returns a String) by streaming into an existing Writer.
-//
-// Example:
-//   impl(MyType, Display(
-//     display : (fn(self: *(Self), writer: Writer) -> Writer)(
-//       writer.write_str("MyType(").write_i64(i64(self.value)).write_str(")")
-//     )
-//   ));
+//! Display trait for streaming formatted output to a Writer.
+//!
+//! # Example
+//!
+//! ```rust
+//! impl(MyType, Display(
+//!   display : (fn(self: *(Self), writer: Writer) -> Writer)(
+//!     writer.write_str("MyType(").write_i64(i64(self.value)).write_str(")")
+//!   )
+//! ));
+//! ```
 
 { Writer } :: import "./writer";
 
-// ============================================================================
-// Display trait
-// ============================================================================
+/// Trait for formatting values by writing to a `Writer` rather than allocating a `String`.
+/// Complement to `ToString` for streaming output into an existing buffer.
 
-Display :: (fn(comptime(T) : Type) -> comptime(Type))
+Display :: (fn(comptime(T) : Type) -> comptime(Trait))
   trait(
-    display :: (fn(self: *(T), writer: Writer) -> Writer)
+    display : (fn(self: *(T), writer: Writer) -> Writer)
   )
 ;
 

package/std/fmt/index.yo

@@ -1,16 +1,12 @@
+//! Formatted output to stdout and stderr.
+
 { fwrite, stdout, stderr } :: import "../libc/stdio";
 { String } :: import "../string";
 { ToString } :: import "./to_string.yo";
 
 export ToString;
 
-/**
- * Print a value that implements ToString to stdout, with a newline.
- * 
- * Example:
- *   println(42);       // prints "42\n"
- *   println("hello");  // prints "hello\n"
- */
+/// Print a value that implements `ToString` to stdout, followed by a newline.
 println :: (fn(forall(T : Type), v : T, where(T <: ToString)) -> unit)({
   s := v.to_string();
   str_bytes := s.as_bytes();
@@ -26,13 +22,7 @@ println :: (fn(forall(T : Type), v : T, where(T <: ToString)) -> unit)({
 });
 export println;
 
-/**
- * Print a value that implements ToString to stdout, without a newline.
- * 
- * Example:
- *   print("hello ");
- *   print("world");   // prints "hello world"
- */
+/// Print a value that implements `ToString` to stdout, without a trailing newline.
 print :: (fn(forall(T : Type), v : T, where(T <: ToString)) -> unit)({
   s := v.to_string();
   str_bytes := s.as_bytes();
@@ -47,12 +37,7 @@ print :: (fn(forall(T : Type), v : T, where(T <: ToString)) -> unit)({
 });
 export print;
 
-/**
- * Print a value that implements ToString to stderr, with a newline.
- * 
- * Example:
- *   eprintln("Error: something went wrong");
- */
+/// Print a value that implements `ToString` to stderr, followed by a newline.
 eprintln :: (fn(forall(T : Type), v : T, where(T <: ToString)) -> unit)({
   s := v.to_string();
   str_bytes := s.as_bytes();
@@ -68,13 +53,7 @@ eprintln :: (fn(forall(T : Type), v : T, where(T <: ToString)) -> unit)({
 });
 export eprintln;
 
-/**
- * Print a value that implements ToString to stderr, without a newline.
- * 
- * Example:
- *   eprint("Warning: ");
- *   eprintln("be careful");
- */
+/// Print a value that implements `ToString` to stderr, without a trailing newline.
 eprint :: (fn(forall(T : Type), v : T, where(T <: ToString)) -> unit)({
   s := v.to_string();
   str_bytes := s.as_bytes();

package/std/fmt/to_string.yo

@@ -1,16 +1,10 @@
+//! ToString trait and implementations for all primitive types.
+
 { String, rune } :: import "../string";
 { snprintf } :: import "../libc/stdio";
 
-/**
- * ToString - A trait for converting values to String representation.
- * 
- * This is similar to:
- * - Rust's `std::fmt::Display` / `ToString` trait
- * - Go's `fmt.Stringer` interface
- * - Java's `Object.toString()` method
- * 
- * Types implementing this trait can be used with `println`, `print`, and `format`.
- */
+/// Trait for converting values to their `String` representation.
+/// Types implementing this trait can be used with `println`, `print`, and template strings.
 ToString :: trait(
   to_string : (fn(self: *(Self)) -> String)
 );