@shd101wyy/yo 0.1.12 → 0.1.14

package/std/build.yo

@@ -1,45 +1,65 @@
-// Build System Module
-//
-// Provides the declarative build API for Yo projects.
-// All functions are compile-time only — they register build artifacts
-// and steps that the build runner uses to orchestrate compilation.
-//
-// Usage in build.yo:
-//   build :: import "std/build";
-//   mod :: build.module({ name: "my-app", root: "./src/lib.yo" });
-//   exe :: build.executable({ name: "my-app", root: "./src/main.yo" });
-//   install :: build.step("install", "Build all artifacts");
-//   install.depend_on(exe);
+//! Declarative build API for Yo projects.
+//!
+//! All functions are compile-time only — they register build artifacts
+//! and steps that the build runner uses to orchestrate compilation.
+//!
+//! # Example
+//!
+//! ```rust
+//! build :: import "std/build";
+//!
+//! mod  :: build.module({ name: "my-lib", root: "./src/lib.yo" });
+//! exe  :: build.executable({ name: "my-app", root: "./src/main.yo" });
+//! install :: build.step("install", "Build all artifacts");
+//! install.depend_on(exe);
+//! ```
 
 // ── Optimization levels ──────────────────────────────────────────────
 
+/// Optimization level for compiled artifacts.
 Optimize :: enum(
+  /// No optimizations, full debug info.  
+  /// Compiler Flags: `-O0 -g`
   Debug,
+  /// Optimized with safety checks.  
+  /// Compiler Flags: `-O2 -g`
   ReleaseSafe,
+  /// Maximum speed optimizations.  
+  /// Compiler Flags: `-O3`
   ReleaseFast,
+  /// Optimize for binary size.  
+  /// Compiler Flags `-O2`
   ReleaseSmall
 );
 export Optimize;
 
 // ── Memory allocators ────────────────────────────────────────────────
 
+/// Memory allocator to use in the compiled artifact.
 Allocator :: enum(
+  /// High-performance allocator (mimalloc).
   Mimalloc,
+  /// Standard C library malloc.
   Libc
 );
 export Allocator;
 
 // ── Sanitizers ───────────────────────────────────────────────────────
 
+/// Runtime sanitizer to enable.
 Sanitize :: enum(
+  /// No sanitizer.
   None,
+  /// AddressSanitizer — detects memory errors and leaks.
   Address,
+  /// LeakSanitizer — detects memory leaks only.
   Leak
 );
 export Sanitize;
 
 // ── Step kinds ───────────────────────────────────────────────────────
 
+/// Kind of build step.
 StepKind :: enum(
   Executable,
   StaticLibrary,
@@ -47,7 +67,8 @@ StepKind :: enum(
   SystemLibrary,
   TestSuite,
   Run,
-  Custom
+  Custom,
+  Documentation
 );
 export StepKind;
 
@@ -68,89 +89,118 @@ export CompilationTarget;
 
 // ── Target utilities ─────────────────────────────────────────────────
 
+/// Host compilation target string.
 target_host :: __yo_build_target_host();
 export target_host;
 
 // ── Config struct types ──────────────────────────────────────────────
-// Struct types with defaults, like Zig's options structs.
-// Usage: build.executable({ name: "app", root: "./src/main.yo" })
-// Unspecified fields get their default values.
 
+/// Configuration for building an executable.
 Executable :: struct(
+  /// Artifact name.
   name : comptime_string,
+  /// Root source file.
   root : comptime_string,
+  /// Compilation target triple (defaults to host).
   (target : comptime_string) ?= __yo_build_target_host(),
+  /// Optimization level.
   (optimize : Optimize) ?= Optimize.Debug,
+  /// Memory allocator.
   (allocator : Allocator) ?= Allocator.Libc,
+  /// Runtime sanitizer.
   (sanitize : Sanitize) ?= Sanitize.None
 );
 export Executable;
 
+/// Configuration for building a static library.
 StaticLibrary :: struct(
+  /// Artifact name.
   name : comptime_string,
+  /// Root source file.
   root : comptime_string,
+  /// Compilation target triple (defaults to host).
   (target : comptime_string) ?= __yo_build_target_host(),
+  /// Optimization level.
   (optimize : Optimize) ?= Optimize.Debug
 );
 export StaticLibrary;
 
+/// Configuration for building a shared/dynamic library.
 SharedLibrary :: struct(
+  /// Artifact name.
   name : comptime_string,
+  /// Root source file.
   root : comptime_string,
+  /// Compilation target triple (defaults to host).
   (target : comptime_string) ?= __yo_build_target_host(),
+  /// Optimization level.
   (optimize : Optimize) ?= Optimize.Debug
 );
 export SharedLibrary;
 
+/// Configuration for a test suite.
 TestSuite :: struct(
+  /// Suite name.
   name : comptime_string,
+  /// Root test file.
   root : comptime_string,
+  /// Compilation target triple (defaults to host).
   (target : comptime_string) ?= __yo_build_target_host()
 );
 export TestSuite;
 
 // ── Build module type ────────────────────────────────────────────────
-// Represents a named source module that declares system library requirements.
-// Modules are the unit of reuse across Yo dependencies.
 
+/// Represents a named source module that declares system library requirements.
+/// Modules are the unit of reuse across Yo dependencies.
 BuildModule :: struct(
+  /// Module name.
   name : comptime_string,
+  /// Root source file.
   root : comptime_string,
-  _dep : comptime_string  // dependency name, empty for local modules
+  _dep : comptime_string
 );
 export BuildModule;
 
 // ── Import entry type ────────────────────────────────────────────────
-// Pairs an import name with a module for use with add_import/add_import_list.
 
+/// Pairs an import name with a module for use with `add_import`/`add_import_list`.
 ImportEntry :: struct(
+  /// Import alias used in source code.
   name : comptime_string,
+  /// The module to import.
   module : BuildModule
 );
 export ImportEntry;
 
 // ── Step type ────────────────────────────────────────────────────────
-// Returned by all build functions. Used to wire dependencies between steps.
 
+/// A build step returned by all registration functions.
+/// Use `step.depend_on(dep)` to wire dependencies between steps.
 Step :: struct(
+  /// Step name.
   name : comptime_string,
+  /// Kind of step.
   kind : StepKind
 );
 export Step;
 
 // ── Step methods ─────────────────────────────────────────────────────
-// Methods on Step for Zig-like API: step.depend_on(other), exe.link(lib).
 
 impl(Step,
+  /// Add a dependency — `dep` must complete before this step runs.
   depend_on : (fn(comptime(self) : Self, comptime(dep) : Step) -> comptime(unit))({
     __yo_build_step_depend_on(self.name, dep.name, dep.kind);
   }),
+  /// Link a library step into this step.
   link : (fn(comptime(self) : Self, comptime(library) : Step) -> comptime(unit))({
     __yo_build_link(self.name, library.name);
   }),
+  /// Add a single module import to this step.
   add_import : (fn(comptime(self) : Self, comptime(entry) : ImportEntry) -> comptime(unit))({
     __yo_build_add_import(self.name, entry.name, entry.module.name, entry.module._dep);
   }),
+  /// Add a list of module imports to this step.
   add_import_list : (fn(comptime(self) : Self, comptime(entries) : ComptimeList(ImportEntry)) -> comptime(unit))({
     cond(
       (entries.len() == usize(0)) => (),
@@ -160,6 +210,7 @@ impl(Step,
       }
     )
   }),
+  /// Add extra C compiler flags to this step.
   add_c_flags : (fn(comptime(self) : Self, comptime(flags) : comptime_string) -> comptime(unit))({
     __yo_build_add_cflags(self.name, flags);
   })
@@ -168,6 +219,7 @@ impl(Step,
 // ── Build module methods ─────────────────────────────────────────────
 
 impl(BuildModule,
+  /// Link a system library into this module.
   link : (fn(comptime(self) : Self, comptime(library) : Step) -> comptime(unit))({
     __yo_build_module_link(self.name, library.name);
   })
@@ -177,34 +229,52 @@ impl(BuildModule,
 // Like Zig's b.option(), declare user-configurable options.
 // CLI usage: yo build -Dname=value
 
+/// User-configurable build option (declared in `build.yo`, set via `yo build -Dname=value`).
 BuildOption :: struct(
+  /// Option name (used with `-D`).
   name : comptime_string,
+  /// Human-readable description.
   description : comptime_string,
+  /// Default value if not provided.
   (default : comptime_string) ?= ""
 );
 export BuildOption;
 
 // ── Dependency config types ──────────────────────────────────────────
 
+/// Git-hosted dependency configuration.
 GitDependency :: struct(
+  /// Dependency name.
   name : comptime_string,
+  /// Git repository URL.
   url : comptime_string,
+  /// Git ref (tag, branch, or commit SHA). Defaults to `"HEAD"`.
   (ref : comptime_string) ?= "HEAD",
+  /// Subdirectory within the repository.
   (path : comptime_string) ?= ""
 );
 export GitDependency;
 
+/// Local path dependency configuration.
 PathDependency :: struct(
+  /// Dependency name.
   name : comptime_string,
+  /// Filesystem path to the dependency root.
   path : comptime_string
 );
 export PathDependency;
 
+/// System C library discovered via `pkg-config`.
 SystemLibrary :: struct(
+  /// Library name (passed to `pkg-config`).
   name : comptime_string,
+  /// Fallback include path if pkg-config fails.
   (fallback_include : comptime_string) ?= "",
+  /// Fallback library path.
   (fallback_lib : comptime_string) ?= "",
+  /// Fallback link flags.
   (fallback_link : comptime_string) ?= "",
+  /// Extra C preprocessor defines.
   (defines : comptime_string) ?= ""
 );
 export SystemLibrary;
@@ -213,20 +283,21 @@ export SystemLibrary;
 // Returned by build.dependency() and build.path_dependency().
 // Provides access to artifacts defined in the dependency's build.yo.
 
+/// Handle to a registered dependency. Use `.artifact()` or `.module()` to access its exports.
 Dependency :: struct(
   name : comptime_string
 );
 export Dependency;
 
 impl(Dependency,
-  // Access a named artifact from the dependency's build.yo.
-  // Returns a Step that can be linked to the consumer's artifacts.
+  /// Access a named artifact from the dependency's `build.yo`.
+  /// Returns a `Step` that can be linked to the consumer's artifacts.
   artifact : (fn(comptime(self) : Self, comptime(artifact_name) : comptime_string) -> comptime(Step))({
     __yo_build_dep_artifact(self.name, artifact_name);
     Step(name: artifact_name, kind: StepKind.StaticLibrary)
   }),
-  // Get a module from the dependency's build.yo.
-  // Empty module_name defaults to the sole module if exactly one exists.
+  /// Get a module from the dependency's `build.yo`.
+  /// Empty `module_name` defaults to the sole module if exactly one exists.
   module : (fn(comptime(self) : Self, (comptime(module_name) : comptime_string) ?= "") -> comptime(BuildModule))({
     _encoded :: __yo_build_dep_module(self.name, module_name);
     BuildModule(name: module_name, root: "", _dep: self.name)
@@ -237,7 +308,7 @@ impl(Dependency,
 // All registration functions return a Step value, allowing steps to be
 // wired together as dependencies via step.depend_on(dep).
 
-// Register an executable artifact. Returns a Step for dependency wiring.
+/// Register an executable artifact. Returns a `Step` for dependency wiring.
 executable :: (fn(comptime(config) : Executable) -> comptime(Step)) {
   opt_str :: match(config.optimize,
     .Debug => "debug",
@@ -259,7 +330,7 @@ executable :: (fn(comptime(config) : Executable) -> comptime(Step)) {
 };
 export executable;
 
-// Register a static library artifact. Returns a Step for dependency wiring.
+/// Register a static library artifact. Returns a `Step` for dependency wiring.
 static_library :: (fn(comptime(config) : StaticLibrary) -> comptime(Step)) {
   opt_str :: match(config.optimize,
     .Debug => "debug",
@@ -272,7 +343,7 @@ static_library :: (fn(comptime(config) : StaticLibrary) -> comptime(Step)) {
 };
 export static_library;
 
-// Register a shared/dynamic library artifact. Returns a Step for dependency wiring.
+/// Register a shared/dynamic library artifact. Returns a `Step` for dependency wiring.
 shared_library :: (fn(comptime(config) : SharedLibrary) -> comptime(Step)) {
   opt_str :: match(config.optimize,
     .Debug => "debug",
@@ -285,21 +356,21 @@ shared_library :: (fn(comptime(config) : SharedLibrary) -> comptime(Step)) {
 };
 export shared_library;
 
-// Register a test suite. Returns a Step for dependency wiring.
+/// Register a test-suite artifact. Returns a `Step` for dependency wiring.
 test :: (fn(comptime(config) : TestSuite) -> comptime(Step)) {
   __yo_build_test(config.name, config.root, config.target);
   Step(name: config.name, kind: StepKind.TestSuite)
 };
 export test;
 
-// Create a run step (compile + execute an artifact). Returns a Step.
+/// Create a run step (compile + execute an artifact). Returns a `Step`.
 run :: (fn(comptime(artifact) : Step) -> comptime(Step)) {
   __yo_build_run(artifact.name);
   Step(name: artifact.name, kind: StepKind.Run)
 };
 export run;
 
-// Register a named build step. Use step.depend_on(dep) to add dependencies.
+/// Register a named build step. Use `step.depend_on(dep)` to add dependencies.
 step :: (fn(
   comptime(name) : comptime_string,
   comptime(description) : comptime_string
@@ -309,47 +380,126 @@ step :: (fn(
 };
 export step;
 
-// Register a git-hosted dependency. Returns a Dependency handle for accessing artifacts.
+/// Register a git-hosted dependency. Returns a `Dependency` handle for accessing artifacts.
 dependency :: (fn(comptime(config) : GitDependency) -> comptime(Dependency)) {
   __yo_build_dependency(config.name, config.url, config.ref, config.path);
   Dependency(name: config.name)
 };
 export dependency;
 
-// Register a local path dependency. Returns a Dependency handle for accessing artifacts.
+/// Register a local path dependency. Returns a `Dependency` handle for accessing artifacts.
 path_dependency :: (fn(comptime(config) : PathDependency) -> comptime(Dependency)) {
   __yo_build_path_dependency(config.name, config.path);
   Dependency(name: config.name)
 };
 export path_dependency;
 
-// Register a system C library discovered via pkg-config. Returns a Step for linking.
+/// Register a system C library discovered via `pkg-config`. Returns a `Step` for linking.
 system_library :: (fn(comptime(config) : SystemLibrary) -> comptime(Step)) {
   __yo_build_system_library(config.name, config.fallback_include, config.fallback_lib, config.fallback_link, config.defines);
   Step(name: config.name, kind: StepKind.SystemLibrary)
 };
 export system_library;
 
-// ── Module config type ───────────────────────────────────────────────
-
+/// Module configuration for shared compilation units.
 ModuleConfig :: struct(
+  /// Module name.
   name : comptime_string,
+  /// Root source file for the module.
   root : comptime_string
 );
 export ModuleConfig;
 
-// Register a named module. Returns a BuildModule for linking system libraries
-// and importing into executables/libraries.
+/// Register a named module. Returns a `BuildModule` for linking system libraries
+/// and importing into executables/libraries.
 _module :: (fn(comptime(config) : ModuleConfig) -> comptime(BuildModule)) {
   __yo_build_module(config.name, config.root);
   BuildModule(name: config.name, root: config.root, _dep: "")
 };
 export module : _module;
 
-// Declare a user-configurable build option.
-// Returns the option value (from CLI -Dname=value, or the default).
-// Usage: strip :: build.option({ name: "strip", description: "Strip debug symbols", default: "false" });
+/// Declare a user-configurable build option.
+/// Returns the option value (from CLI `-Dname=value`, or the default).
+///
+/// # Example
+/// ```rust
+/// strip :: build.option({
+///   name: "strip",
+///   description: "Strip debug symbols",
+///   default: "false"
+/// });
+/// ```
 option :: (fn(comptime(config) : BuildOption) -> comptime(str))(
   __yo_build_option(config.name, config.description, config.default)
 );
 export option;
+
+// ── Documentation generation ─────────────────────────────────────────
+
+/// Output format for documentation generation.
+DocFormat :: enum(
+  Html,
+  Markdown,
+  Json
+);
+export DocFormat;
+
+/// Configuration for documentation generation.
+DocConfig :: struct(
+  /// Step name (e.g., "doc").
+  name : comptime_string,
+  /// Root source file or directory to document.
+  root : comptime_string,
+  /// Output directory (default: "yo-out/doc").
+  (output : comptime_string) ?= "yo-out/doc",
+  /// Output format (default: Html).
+  (format : DocFormat) ?= DocFormat.Html,
+  /// Document non-exported (private) items.
+  (include_private : bool) ?= false,
+  /// Document dependencies too.
+  (include_deps : bool) ?= false,
+  /// Custom site title (default: project name).
+  (title : comptime_string) ?= "",
+  /// Path to logo image.
+  (logo : comptime_string) ?= "",
+  /// Path to favicon.
+  (favicon : comptime_string) ?= ""
+);
+export DocConfig;
+
+/// Register a documentation generation step. Returns a Step for dependency wiring.
+///
+/// # Examples
+///
+/// ```rust
+/// build :: import "std/build";
+///
+/// // Minimal — just works with defaults
+/// doc_step :: build.doc({ name: "doc", root: "./src/lib.yo" });
+///
+/// // Full customization
+/// doc_step :: build.doc({
+///   name: "doc",
+///   root: "./src",
+///   output: "docs/api",
+///   format: DocFormat.Markdown,
+///   title: "My Library API"
+/// });
+///
+/// install :: build.step("install", "Build all artifacts");
+/// install.depend_on(doc_step);
+/// ```
+doc :: (fn(comptime(config) : DocConfig) -> comptime(Step)) {
+  fmt_str :: match(config.format,
+    .Html => "html",
+    .Markdown => "markdown",
+    .Json => "json"
+  );
+  __yo_build_doc(
+    config.name, config.root, config.output, fmt_str,
+    config.include_private, config.include_deps,
+    config.title, config.logo, config.favicon
+  );
+  Step(name: config.name, kind: StepKind.Documentation)
+};
+export doc;

package/std/cli/arg_parser.yo

@@ -1,17 +1,49 @@
+//! Command-line argument parsing.
+//!
+//! Supports flags (`--verbose`), options (`--output file`), short aliases (`-v`),
+//! and positional arguments. Automatically generates help text.
+//!
+//! # Example
+//!
+//! ```rust
+//! { ArgParser } :: import "std/cli/arg_parser";
+//!
+//! parser := ArgParser.new(`myapp`, `A sample CLI tool`);
+//! parser.flag(`verbose`, `v`, `Enable verbose output`);
+//! parser.option(`output`, `o`, `Output file`, `out.txt`);
+//! args := parser.parse();
+//! ```
+
 open import "../collections/array_list";
 open import "../string";
 
-ArgKind :: enum(Flag, Opt, Positional);
+/// Kind of command-line argument.
+ArgKind :: enum(
+  /// Boolean flag (e.g. `--verbose`).
+  Flag,
+  /// Key-value option (e.g. `--output file`).
+  Opt,
+  /// Positional argument.
+  Positional
+);
 
+/// Definition of a single command-line argument.
 ArgDef :: object(
+  /// Long name (e.g. `"verbose"` for `--verbose`).
   _long_name : String,
+  /// Short name (e.g. `"v"` for `-v`).
   _short_name : String,
+  /// Human-readable description for help text.
   _description : String,
+  /// Kind of argument (flag, option, or positional).
   _kind : ArgKind,
+  /// Default value for options.
   _default_value : String,
+  /// Whether this argument is required.
   _required : bool
 );
 
+/// Result of parsing command-line arguments.
 ParsedArgs :: object(
   _set_flags : ArrayList(String),
   _option_names : ArrayList(String),
@@ -20,9 +52,13 @@ ParsedArgs :: object(
   _positional_names : ArrayList(String)
 );
 
+/// Command-line argument parser.
 ArgParser :: object(
+  /// Application name shown in help text.
   _name : String,
+  /// Application description shown in help text.
   _description : String,
+  /// Registered argument definitions.
   _args : ArrayList(ArgDef)
 );
 

package/std/collections/array_list.yo

@@ -1,33 +1,21 @@
-/**
- * ArrayList - A dynamic array implementation for Yo language
- * 
- * Similar to Rust's Vec<T> and Zig's ArrayList, this ArrayList provides:
- * - Dynamic resizing
- * - ~~Memory management via custom allocator~~
- * - Type safety
- * - RAII for automatic cleanup
- */
+//! Dynamic array (vector) with amortized O(1) push and O(1) indexed access.
+
 { GlobalAllocator, AllocError } :: import "../allocator.yo";
 { memmove, memcpy, memset } :: import "../libc/string.yo";
 { malloc, calloc, realloc, free, aligned_alloc } :: GlobalAllocator;
 
-/**
- * ArrayList error types
- */
+/// Error variants for ArrayList operations.
 ArrayListError :: enum(
+  /// Memory allocation failed.
   AllocError(error : AllocError),
+  /// Index is out of bounds for the current length.
   IndexOutOfBounds(index: usize, length: usize),
+  /// Attempted to access an element from an empty list.
   EmptyList
 );
 
-/**
- * ArrayList type - a growable array
- * 
- * Memory layout:
- * - ptr: pointer to the heap-allocated buffer
- * - _length: current number of elements
- * - _capacity: total capacity of the buffer
- */
+/// Generic growable array similar to Rust's `Vec<T>`.
+/// Heap-allocated with automatic resizing and reference-counted cleanup.
 ArrayList :: (fn(comptime(T): Type) -> comptime(Type))(
   object(
     _ptr : ?*(T),

package/std/collections/btree_map.yo

@@ -1,23 +1,20 @@
-// std/collections/btree_map.yo - Sorted map backed by a sorted ArrayList
-//
-// BTreeMap maintains entries sorted by key, enabling ordered iteration and
-// O(log n) lookups via binary search. Insert is O(n) (shift-based).
-//
-// Example:
-//   { BTreeMap } :: import "std/collections/btree_map";
-//
-//   m := BTreeMap(String, i32).new();
-//   m.set(String.from("b"), 2);
-//   m.set(String.from("a"), 1);
-//   // Iteration order: a, b
+//! Sorted map backed by a sorted array with O(log n) lookup via binary search.
+//!
+//! # Example
+//!
+//! ```rust
+//! { BTreeMap } :: import "std/collections/btree_map";
+//!
+//! m := BTreeMap(String, i32).new();
+//! m.set(String.from("b"), 2);
+//! m.set(String.from("a"), 1);
+//! // Iteration order: a, b
+//! ```
 
 { ArrayList } :: import "./array_list";
 open import "../string";
 
-// ============================================================================
-// BTreeEntry - key/value pair
-// ============================================================================
-
+/// Key-value pair entry stored in a BTreeMap.
 BTreeEntry :: (fn(comptime(K) : Type, comptime(V) : Type) -> comptime(Type))(
   struct(key: K, value: V)
 );
@@ -27,10 +24,8 @@ export BTreeEntry;
 // Internal result from binary search.
 _FindResult :: struct(idx: usize, found: bool);
 
-// ============================================================================
-// BTreeMap
-// ============================================================================
-
+/// Sorted map maintaining entries in key order.
+/// Provides ordered iteration and O(log n) lookup via binary search. Insert is O(n).
 BTreeMap :: (fn(comptime(K) : Type, comptime(V) : Type) -> comptime(Type))(
   object(
     _entries : ArrayList(BTreeEntry(K, V))