@shd101wyy/yo 0.1.12 → 0.1.14

package/std/fmt/writer.yo

@@ -1,45 +1,44 @@
-// std/fmt/writer.yo - String Writer
-//
-// A composable, chainable string builder backed by ArrayList(u8).
-// Useful for constructing formatted strings without intermediate allocations.
-//
-// Example:
-//   { Writer, Alignment } :: import "std/fmt/writer";
-//
-//   w := Writer.new()
-//     .write_str("hello ")
-//     .write_str("world")
-//     .write_byte(u8(33));
-//   s := w.to_string();  // "hello world!"
+//! Chainable string builder for composing formatted output.
+//!
+//! # Example
+//!
+//! ```rust
+//! { Writer, Alignment } :: import "std/fmt/writer";
+//!
+//! w := Writer.new()
+//!   .write_str("hello ")
+//!   .write_str("world")
+//!   .write_byte(u8(33));
+//! s := w.to_string();  // "hello world!"
+//! ```
 
 { String } :: import "../string";
 { ArrayList } :: import "../collections/array_list";
 { rune } :: import "../string/rune";
 { snprintf } :: import "../libc/stdio";
 
+/// Text alignment for padded output.
 Alignment :: enum(Left, Right, Center);
 export Alignment;
 
-// ============================================================================
-// Writer - chainable string builder
-// ============================================================================
-
+/// Chainable string builder backed by `ArrayList(u8)`.
+/// Useful for constructing formatted strings without intermediate allocations.
 Writer :: object(
   buf : ArrayList(u8)
 );
 
 impl(Writer,
-  // Create a new empty Writer.
+  /// Create a new empty Writer.
   new : (fn() -> Self)(
     Self(buf: ArrayList(u8).new())
   ),
 
-  // Create a Writer pre-allocated with the given byte capacity.
+  /// Create a Writer pre-allocated with the given byte capacity.
   with_capacity : (fn(cap: usize) -> Self)(
     Self(buf: ArrayList(u8).with_capacity(cap))
   ),
 
-  // Append a str literal (byte slice) to the Writer.
+  /// Append a `str` literal (byte slice) to the Writer.
   write_str : (fn(self: Self, s: str) -> Self)({
     i := usize(0);
     while (i < s.len()),
@@ -50,7 +49,7 @@ impl(Writer,
     self
   }),
 
-  // Append a String (owned UTF-8) to the Writer.
+  /// Append a String (owned UTF-8) to the Writer.
   write_string : (fn(self: Self, s: String) -> Self)({
     bytes := s.as_bytes();
     i := usize(0);
@@ -62,13 +61,13 @@ impl(Writer,
     self
   }),
 
-  // Append a single byte to the Writer.
+  /// Append a single byte to the Writer.
   write_byte : (fn(self: Self, b: u8) -> Self)({
     self.buf.push(b);
     self
   }),
 
-  // Append an ArrayList(u8) of bytes to the Writer.
+  /// Append an ArrayList(u8) of bytes to the Writer.
   write_bytes : (fn(self: Self, data: ArrayList(u8)) -> Self)({
     i := usize(0);
     while (i < data.len()),
@@ -79,7 +78,7 @@ impl(Writer,
     self
   }),
 
-  // Append a Unicode code point encoded as UTF-8.
+  /// Append a Unicode code point encoded as UTF-8.
   write_rune : (fn(self: Self, r: rune) -> Self)({
     v := u32(r.char);
     cond(
@@ -105,7 +104,7 @@ impl(Writer,
     self
   }),
 
-  // Append a signed 64-bit integer in decimal.
+  /// Append a signed 64-bit integer in decimal.
   write_i64 : (fn(self: Self, n: i64) -> Self)({
     buf := Array(u8, usize(24)).fill(u8(0));
     buf_ptr := &(buf(usize(0)));
@@ -114,7 +113,7 @@ impl(Writer,
     self.write_string(s)
   }),
 
-  // Append an unsigned 64-bit integer in decimal.
+  /// Append an unsigned 64-bit integer in decimal.
   write_u64 : (fn(self: Self, n: u64) -> Self)({
     buf := Array(u8, usize(24)).fill(u8(0));
     buf_ptr := &(buf(usize(0)));
@@ -123,7 +122,7 @@ impl(Writer,
     self.write_string(s)
   }),
 
-  // Append a 64-bit float with the given number of decimal places.
+  /// Append a 64-bit float with the given number of decimal places.
   write_f64 : (fn(self: Self, n: f64, precision: i32) -> Self)({
     buf := Array(u8, usize(64)).fill(u8(0));
     buf_ptr := &(buf(usize(0)));
@@ -132,7 +131,7 @@ impl(Writer,
     self.write_string(s)
   }),
 
-  // Append a bool as "true" or "false".
+  /// Append a bool as "true" or "false".
   write_bool : (fn(self: Self, b: bool) -> Self)(
     cond(
       b => self.write_str("true"),
@@ -140,7 +139,7 @@ impl(Writer,
     )
   ),
 
-  // Append an unsigned 64-bit integer in lowercase hexadecimal.
+  /// Append an unsigned 64-bit integer in lowercase hexadecimal.
   write_hex : (fn(self: Self, n: u64) -> Self)({
     buf := Array(u8, usize(20)).fill(u8(0));
     buf_ptr := &(buf(usize(0)));
@@ -149,7 +148,7 @@ impl(Writer,
     self.write_string(s)
   }),
 
-  // Append an unsigned 64-bit integer in octal.
+  /// Append an unsigned 64-bit integer in octal.
   write_octal : (fn(self: Self, n: u64) -> Self)({
     buf := Array(u8, usize(24)).fill(u8(0));
     buf_ptr := &(buf(usize(0)));
@@ -158,7 +157,7 @@ impl(Writer,
     self.write_string(s)
   }),
 
-  // Append an unsigned 64-bit integer in binary (no stdlib support — manual).
+  /// Append an unsigned 64-bit integer in binary (no stdlib support — manual).
   write_binary : (fn(self: Self, n: u64) -> Self)({
     cond(
       (n == u64(0)) => {
@@ -186,7 +185,7 @@ impl(Writer,
     self
   }),
 
-  // Append a str padded to width using the given pad rune and alignment.
+  /// Append a str padded to width using the given pad rune and alignment.
   write_padded : (fn(self: Self, s: str, width: usize, pad: rune, align: Alignment) -> Self)({
     len := s.len();
     cond(
@@ -227,12 +226,12 @@ impl(Writer,
     )
   }),
 
-  // Consume the Writer and return an owned String.
+  /// Consume the Writer and return an owned String.
   to_string : (fn(self: Self) -> String)(
     String.from_bytes(self.buf)
   ),
 
-  // Return the current byte length of the buffer.
+  /// Return the current byte length of the buffer.
   len : (fn(self: Self) -> usize)(
     self.buf.len()
   )

package/std/fs/dir.yo

@@ -1,22 +1,25 @@
-// std/fs/dir.yo - High-level directory operations
-//
-// Wraps low-level std/sys/dir with typed APIs using Exception effect.
-//
-// Example:
-//   { create_dir, remove_dir, read_dir } :: import "std/fs/dir";
-//   { Path } :: import "std/path";
-//
-//   main :: (fn(using(io : IO)) -> unit)({
-//     given(exn) : Exception = {
-//       throw : (fn(forall(T : Type), error: AnyError) -> T)(
-//         { println(error.to_string()); exit(i32(1)); }
-//       )
-//     };
-//
-//     io.await(create_dir(Path.new(`/tmp/yo_test`)));
-//     entries := io.await(read_dir(Path.new(`/tmp/yo_test`)));
-//     io.await(remove_dir(Path.new(`/tmp/yo_test`)));
-//   });
+//! Async directory operations — create, remove, read, link, rename.
+//!
+//! Wraps low-level `std/sys/dir` with typed APIs using the `Exception` effect.
+//!
+//! # Example
+//!
+//! ```rust
+//! { create_dir, remove_dir, read_dir } :: import "std/fs/dir";
+//! { Path } :: import "std/path";
+//!
+//! main :: (fn(using(io : IO)) -> unit)({
+//!   given(exn) : Exception = {
+//!     throw : (fn(forall(T : Type), error: AnyError) -> T)(
+//!       { println(error.to_string()); exit(i32(1)); }
+//!     )
+//!   };
+//!
+//!   io.await(create_dir(Path.new(`/tmp/yo_test`)));
+//!   entries := io.await(read_dir(Path.new(`/tmp/yo_test`)));
+//!   io.await(remove_dir(Path.new(`/tmp/yo_test`)));
+//! });
+//! ```
 
 { GlobalAllocator } :: import "../allocator";
 { malloc, free } :: GlobalAllocator;
@@ -39,10 +42,15 @@ IO_file :: import "../sys/file";
 // FileType enum
 // ============================================================================
 
+/// The type of a file system entry.
 FileType :: enum(
+  /// A regular file.
   File,
+  /// A directory.
   Directory,
+  /// A symbolic link.
   Symlink,
+  /// An unknown or unsupported file type.
   Other
 );
 
@@ -52,6 +60,7 @@ export FileType;
 // DirEntry
 // ============================================================================
 
+/// A directory entry containing the entry name, file type, and inode number.
 DirEntry :: struct(
   name      : String,
   file_type : FileType,
@@ -64,7 +73,7 @@ export DirEntry;
 // Directory operations
 // ============================================================================
 
-// Create a directory at the given path.
+/// Create a directory at the given path.
 create_dir :: (fn(path: Path, using(io : IO)) -> Impl(Future(unit, IO, Exception)))(
   io.async((using(io, exn)) => {
     cstr_bytes := path.to_string().to_cstr();
@@ -77,13 +86,13 @@ create_dir :: (fn(path: Path, using(io : IO)) -> Impl(Future(unit, IO, Exception
   })
 );
 
-// Create a directory (str version).
+/// Create a directory (`str` path variant).
 create_dir_str :: (fn(path: str, using(io : IO)) -> Impl(Future(unit, IO, Exception)))(
   create_dir(Path.new(String.from(path)))
 );
 
-// Create a directory and all parent directories.
-// Does not error if the directory already exists.
+/// Create a directory and all missing parent directories.
+/// Does not error if the directory already exists.
 create_dir_all :: (fn(path: Path, using(io : IO)) -> Impl(Future(unit, IO, Exception)))(
   io.async((using(io, exn)) => {
     path_s := path.to_string();
@@ -160,12 +169,12 @@ create_dir_all :: (fn(path: Path, using(io : IO)) -> Impl(Future(unit, IO, Excep
   })
 );
 
-// Create a directory and all parents (str version).
+/// Create a directory and all missing parents (`str` path variant).
 create_dir_all_str :: (fn(path: str, using(io : IO)) -> Impl(Future(unit, IO, Exception)))(
   create_dir_all(Path.new(String.from(path)))
 );
 
-// Remove an empty directory.
+/// Remove an empty directory. Throws if the directory is not empty.
 remove_dir :: (fn(path: Path, using(io : IO)) -> Impl(Future(unit, IO, Exception)))(
   io.async((using(io, exn)) => {
     cstr_bytes := path.to_string().to_cstr();
@@ -182,7 +191,7 @@ remove_dir_str :: (fn(path: str, using(io : IO)) -> Impl(Future(unit, IO, Except
   remove_dir(Path.new(String.from(path)))
 );
 
-// Remove a file.
+/// Remove a file at the given path.
 remove_file :: (fn(path: Path, using(io : IO)) -> Impl(Future(unit, IO, Exception)))(
   io.async((using(io, exn)) => {
     cstr_bytes := path.to_string().to_cstr();
@@ -199,7 +208,7 @@ remove_file_str :: (fn(path: str, using(io : IO)) -> Impl(Future(unit, IO, Excep
   remove_file(Path.new(String.from(path)))
 ;
 
-// Rename/move a file or directory.
+/// Rename or move a file or directory from `from` to `to`.
 rename :: (fn(from: Path, to: Path, using(io : IO)) -> Impl(Future(unit, IO, Exception)))(
   io.async((using(io, exn)) => {
     from_cstr_bytes := from.to_string().to_cstr();
@@ -218,7 +227,7 @@ rename_str :: (fn(from: str, to: str, using(io : IO)) -> Impl(Future(unit, IO, E
   rename(Path.new(String.from(from)), Path.new(String.from(to)))
 ;
 
-// Create a hard link from src to dst.
+/// Create a hard link from `src` to `dst`.
 hard_link :: (fn(src: Path, dst: Path, using(io : IO)) -> Impl(Future(unit, IO, Exception)))(
   io.async((using(io, exn)) => {
     src_cstr_bytes := src.to_string().to_cstr();
@@ -237,7 +246,7 @@ hard_link_str :: (fn(src: str, dst: str, using(io : IO)) -> Impl(Future(unit, IO
   hard_link(Path.new(String.from(src)), Path.new(String.from(dst)))
 ;
 
-// Create a symbolic link at dst pointing to src.
+/// Create a symbolic link at `dst` pointing to `src`.
 symlink :: (fn(src: Path, dst: Path, using(io : IO)) -> Impl(Future(unit, IO, Exception)))(
   io.async((using(io, exn)) => {
     src_cstr_bytes := src.to_string().to_cstr();
@@ -260,7 +269,8 @@ symlink_str :: (fn(src: str, dst: str, using(io : IO)) -> Impl(Future(unit, IO,
 // Directory listing
 // ============================================================================
 
-// Read directory entries from a path.
+/// Read all entries from a directory, returning an `ArrayList(DirEntry)`.
+/// Skips the `.` and `..` entries.
 read_dir :: (fn(path: Path, using(io : IO)) -> Impl(Future(ArrayList(DirEntry), IO, Exception)))(
   io.async((using(io, exn)) => {
     cstr_bytes := path.to_string().to_cstr();