@shd101wyy/yo 0.1.12 → 0.1.13

package/std/net/addr.yo

@@ -1,3 +1,4 @@
+//! Network address types — IP addresses and socket addresses.
 // std/net/addr.yo - Network address types
 //
 // High-level IP address and socket address types.
@@ -25,14 +26,17 @@ _ASCII_DOT  :: u8(46);  // '.'
 _ASCII_ZERO :: u8(48);  // '0'
 _ASCII_NINE :: u8(57);  // '9'
 
+/// An IP address, either IPv4 or IPv6.
 IpAddr :: enum(
+  /// An IPv4 address represented as four octets.
   V4(a: u8, b: u8, c: u8, d: u8),
+  /// An IPv6 address represented as eight 16-bit segments.
   V6(segments: Array(u16, usize(8)))
 );
 
 impl(IpAddr,
-  // Parse an IPv4 address from a String like "127.0.0.1".
-  // Only supports IPv4 dotted-decimal notation.
+  /// Parse an IPv4 address from a dotted-decimal `String` (e.g. "127.0.0.1").
+  /// Throws on invalid input.
   parse_v4 : (fn(s: String, using(exn : Exception)) -> IpAddr)({
     bytes := s.as_bytes();
     parts := Array(u8, usize(4)).fill(u8(0));
@@ -86,24 +90,24 @@ impl(IpAddr,
     .V4(parts(usize(0)), parts(usize(1)), parts(usize(2)), parts(usize(3)))
   }),
 
-  // IPv4 loopback address (127.0.0.1).
+  /// Return the IPv4 loopback address (127.0.0.1).
   loopback_v4 : (fn() -> IpAddr)(
     .V4(u8(127), u8(0), u8(0), u8(1))
   ),
 
-  // IPv6 loopback address (::1).
+  /// Return the IPv6 loopback address (::1).
   loopback_v6 : (fn() -> IpAddr)({
     segs := Array(u16, usize(8)).fill(u16(0));
     segs(usize(7)) = u16(1);
     .V6(segs)
   }),
 
-  // IPv4 any address (0.0.0.0).
+  /// Return the IPv4 unspecified address (0.0.0.0).
   any_v4 : (fn() -> IpAddr)(
     .V4(u8(0), u8(0), u8(0), u8(0))
   ),
 
-  // Check if this is a loopback address.
+  /// Return `true` if this is a loopback address.
   is_loopback : (fn(self: Self) -> bool)(
     match(self,
       .V4(a, _, _, _) => (a == u8(127)),
@@ -123,7 +127,7 @@ impl(IpAddr,
     )
   ),
 
-  // Check if this is an IPv4 address.
+  /// Return `true` if this is an IPv4 address.
   is_v4 : (fn(self: Self) -> bool)(
     match(self,
       .V4(_, _, _, _) => true,
@@ -131,7 +135,7 @@ impl(IpAddr,
     )
   ),
 
-  // Check if this is an IPv6 address.
+  /// Return `true` if this is an IPv6 address.
   is_v6 : (fn(self: Self) -> bool)(
     match(self,
       .V4(_, _, _, _) => false,
@@ -171,23 +175,26 @@ export IpAddr;
 // SocketAddr
 // ============================================================================
 
+/// An IP address paired with a port number.
 SocketAddr :: struct(
+  /// The IP address.
   ip   : IpAddr,
+  /// The port number.
   port : u16
 );
 
 impl(SocketAddr,
-  // Create a new socket address.
+  /// Create a new socket address from an IP and port.
   new : (fn(ip: IpAddr, port: u16) -> Self)(
     Self(ip: ip, port: port)
   ),
 
-  // Create a socket address for IPv4 loopback with given port.
+  /// Create an IPv4 loopback socket address (127.0.0.1) with the given port.
   loopback : (fn(port: u16) -> Self)(
     Self(ip: IpAddr.loopback_v4(), port: port)
   ),
 
-  // Create a socket address for any IPv4 address with given port.
+  /// Create an IPv4 unspecified socket address (0.0.0.0) with the given port.
   any : (fn(port: u16) -> Self)(
     Self(ip: IpAddr.any_v4(), port: port)
   )

package/std/net/dns.yo

@@ -1,3 +1,4 @@
+//! Async DNS resolution.
 // std/net/dns.yo - High-level DNS resolution
 //
 // Wraps std/sys/dns with typed DNS lookup functions.
@@ -36,7 +37,7 @@ IO_dns :: import "../sys/dns";
 // DNS lookup
 // ============================================================================
 
-// Resolve a hostname to a list of IP addresses.
+/// Resolve a hostname to a list of IP addresses.
 lookup_host :: (fn(host: String, using(io : IO)) -> Impl(Future(ArrayList(IpAddr), IO, Exception)))(
   io.async((using(io : IO, exn : Exception)) => {
     host_cstr_bytes := host.to_cstr();
@@ -84,7 +85,7 @@ lookup_host :: (fn(host: String, using(io : IO)) -> Impl(Future(ArrayList(IpAddr
   })
 );
 
-// Resolve a hostname and port to a list of socket addresses.
+/// Resolve a hostname and port to a list of socket addresses.
 resolve :: (fn(host: String, port: u16, using(io : IO)) -> Impl(Future(ArrayList(SocketAddr), IO, Exception)))(
   io.async((using(io : IO, exn : Exception)) => {
     addrs := io.await(lookup_host(host, using(io)));

package/std/net/errors.yo

@@ -1,3 +1,4 @@
+//! Network error types.
 // std/net/errors.yo - Network error type
 //
 // Higher-level network error that wraps IOError with network-specific variants.
@@ -14,22 +15,34 @@ open import "../string";
 // NetError
 // ============================================================================
 
+/// Network-specific error type wrapping lower-level I/O errors.
 NetError :: enum(
+  /// The remote host refused the connection.
   ConnectionRefused,
+  /// The connection was reset by the remote host.
   ConnectionReset,
+  /// The connection was aborted locally.
   ConnectionAborted,
+  /// The address is already in use.
   AddrInUse,
+  /// The requested address is not available.
   AddrNotAvailable,
+  /// The operation timed out.
   TimedOut,
+  /// The remote host is unreachable.
   HostUnreachable,
+  /// The network is unreachable.
   NetworkUnreachable,
+  /// DNS resolution failed.
   DNSFailed(msg: String),
+  /// A wrapped lower-level I/O error.
   IO(err: IOError),
+  /// An unclassified network error with a message.
   Other(msg: String)
 );
 
 impl(NetError,
-  // Convert an IOError to a NetError.
+  /// Convert an `IOError` into the corresponding `NetError` variant.
   from_io : (fn(err: IOError) -> Self)(
     match(err,
       .ConnectionRefused => .ConnectionRefused,
@@ -67,7 +80,8 @@ impl(NetError, ToString(
 impl(NetError, Error());
 
 impl(NetError,
-  // Check a raw result (positive = ok, negative = -errno) and throw on error.
+  /// Check a raw syscall result and throw on error.
+  /// Positive values are returned as-is; negative values are converted to a `NetError` and thrown.
   check : (fn(result: i32, using(exn : Exception)) -> i32)(
     cond(
       (result >= i32(0)) => result,

package/std/net/tcp.yo

@@ -1,3 +1,4 @@
+//! Async TCP networking — listeners and streams with Exception-based error handling.
 // std/net/tcp.yo - High-level TCP types
 //
 // Wraps std/sys/tcp with typed TcpListener and TcpStream objects.
@@ -63,6 +64,7 @@ _throw_io :: (fn(errno_val: i32, using(exn : Exception)) -> unit)(
 // TcpStream (declared before TcpListener so accept can reference it)
 // ============================================================================
 
+/// A connected TCP stream for bidirectional data transfer.
 TcpStream :: object(
   _fd        : i32,
   _peer_addr : SocketAddr,
@@ -73,6 +75,7 @@ TcpStream :: object(
 // TcpListener
 // ============================================================================
 
+/// A TCP socket that listens for incoming connections.
 TcpListener :: object(
   _fd         : i32,
   _local_addr : SocketAddr,
@@ -80,7 +83,7 @@ TcpListener :: object(
 );
 
 impl(TcpListener,
-  // Bind to a socket address and start listening.
+  /// Bind to a socket address and start listening.
   bind : (fn(addr: SocketAddr, using(io : IO)) -> Impl(Future(TcpListener, IO, Exception)))(
     io.async((using(io : IO, exn : Exception)) => {
       domain := cond(
@@ -118,7 +121,7 @@ impl(TcpListener,
     })
   ),
 
-  // Accept an incoming connection.
+  /// Accept an incoming connection, returning a new `TcpStream`.
   accept : (fn(self: Self, using(io : IO)) -> Impl(Future(TcpStream, IO, Exception)))({
     fd := self._fd;
     io.async((using(io : IO, exn : Exception)) => {
@@ -148,12 +151,12 @@ impl(TcpListener,
     })
   }),
 
-  // Get the local address this listener is bound to.
+  /// Get the local address this listener is bound to.
   local_addr : (fn(self: Self) -> SocketAddr)(
     self._local_addr
   ),
 
-  // Close the listener.
+  /// Close the listener socket.
   close : (fn(self: Self, using(io : IO)) -> Impl(Future(unit, IO, Exception)))({
     fd := self._fd;
     io.async((using(io : IO, exn : Exception)) => {
@@ -171,7 +174,7 @@ impl(TcpListener,
     })
   }),
 
-  // Get the file descriptor.
+  /// Get the underlying file descriptor.
   fd : (fn(self: Self) -> i32)(
     self._fd
   )
@@ -197,7 +200,7 @@ export TcpListener;
 // ============================================================================
 
 impl(TcpStream,
-  // Connect to a remote address.
+  /// Connect to a remote address, returning a new `TcpStream`.
   connect : (fn(addr: SocketAddr, using(io : IO)) -> Impl(Future(TcpStream, IO, Exception)))(
     io.async((using(io : IO, exn : Exception)) => {
       domain := cond(
@@ -224,8 +227,8 @@ impl(TcpStream,
     })
   ),
 
-  // Read bytes from the stream.
-  // Returns the number of bytes read (0 means peer closed).
+  /// Read bytes from the stream into `buf`.
+  /// Returns the number of bytes read, or 0 if the peer closed the connection.
   read : (fn(self: Self, buf: *(u8), size: usize, using(io : IO)) -> Impl(Future(i32, IO, Exception)))({
     fd := self._fd;
     io.async((using(io : IO, exn : Exception)) => {
@@ -234,8 +237,8 @@ impl(TcpStream,
     })
   }),
 
-  // Write a str to the stream.
-  // Returns the number of bytes written.
+  /// Write a `str` to the stream.
+  /// Returns the number of bytes written.
   write_str : (fn(self: Self, data: str, using(io : IO)) -> Impl(Future(i32, IO, Exception)))({
     fd := self._fd;
     s := String.from(data);
@@ -246,8 +249,8 @@ impl(TcpStream,
     })
   }),
 
-  // Write a String to the stream.
-  // Returns the number of bytes written.
+  /// Write a `String` to the stream.
+  /// Returns the number of bytes written.
   write_string : (fn(self: Self, data: String, using(io : IO)) -> Impl(Future(i32, IO, Exception)))({
     fd := self._fd;
     data_bytes := data.as_bytes();
@@ -257,8 +260,8 @@ impl(TcpStream,
     })
   }),
 
-  // Write bytes to the stream.
-  // Returns the number of bytes written.
+  /// Write raw bytes from an `ArrayList(u8)` to the stream.
+  /// Returns the number of bytes written.
   write_bytes : (fn(self: Self, data: ArrayList(u8), using(io : IO)) -> Impl(Future(i32, IO, Exception)))({
     fd := self._fd;
     io.async((using(io : IO, exn : Exception)) => {
@@ -267,7 +270,7 @@ impl(TcpStream,
     })
   }),
 
-  // Read all available data into a byte list.
+  /// Read all available data from the stream into a byte list.
   read_bytes : (fn(self: Self, using(io : IO)) -> Impl(Future(ArrayList(u8), IO, Exception)))({
     fd := self._fd;
     io.async((using(io : IO, exn : Exception)) => {
@@ -300,8 +303,8 @@ impl(TcpStream,
     })
   }),
 
-  // Shut down the connection.
-  // how: 0 = read, 1 = write, 2 = both
+  /// Shut down part or all of the connection.
+  /// `how`: 0 = read, 1 = write, 2 = both.
   shutdown : (fn(self: Self, how: i32, using(io : IO)) -> Impl(Future(unit, IO, Exception)))({
     fd := self._fd;
     io.async((using(io : IO, exn : Exception)) => {
@@ -313,7 +316,7 @@ impl(TcpStream,
     })
   }),
 
-  // Close the stream.
+  /// Close the stream.
   close : (fn(self: Self, using(io : IO)) -> Impl(Future(unit, IO, Exception)))({
     fd := self._fd;
     io.async((using(io : IO, exn : Exception)) => {
@@ -331,17 +334,17 @@ impl(TcpStream,
     })
   }),
 
-  // Get the peer address.
+  /// Get the remote peer's socket address.
   peer_addr : (fn(self: Self) -> SocketAddr)(
     self._peer_addr
   ),
 
-  // Get the file descriptor.
+  /// Get the underlying file descriptor.
   fd : (fn(self: Self) -> i32)(
     self._fd
   ),
 
-  // Enable/disable TCP_NODELAY (Nagle's algorithm).
+  /// Enable or disable TCP_NODELAY (disables Nagle's algorithm).
   set_nodelay : (fn(self: Self, nodelay: bool, using(io : IO)) -> Impl(Future(unit, IO, Exception)))({
     sock_fd := self._fd;
     io.async((using(io : IO, exn : Exception)) => {
@@ -355,7 +358,7 @@ impl(TcpStream,
     })
   }),
 
-  // Enable/disable SO_KEEPALIVE.
+  /// Enable or disable SO_KEEPALIVE on the socket.
   set_keepalive : (fn(self: Self, enabled: bool, using(io : IO)) -> Impl(Future(unit, IO, Exception)))({
     sock_fd := self._fd;
     io.async((using(io : IO, exn : Exception)) => {

package/std/net/udp.yo

@@ -1,3 +1,4 @@
+//! Async UDP networking — connectionless datagram sockets.
 // std/net/udp.yo - High-level UDP socket
 //
 // Wraps std/sys/udp with typed UdpSocket object.
@@ -59,6 +60,7 @@ _throw_net_io :: (fn(errno_val: i32, using(exn : Exception)) -> unit)(
 // UdpSocket
 // ============================================================================
 
+/// A UDP socket for sending and receiving datagrams.
 UdpSocket :: object(
   _fd         : i32,
   _local_addr : SocketAddr,
@@ -66,7 +68,7 @@ UdpSocket :: object(
 );
 
 impl(UdpSocket,
-  // Create and bind a UDP socket to the given address.
+  /// Create and bind a UDP socket to the given address.
   bind : (fn(addr: SocketAddr, using(io : IO)) -> Impl(Future(UdpSocket, IO, Exception)))(
     io.async((using(io : IO, exn : Exception)) => {
       domain := cond(
@@ -89,8 +91,8 @@ impl(UdpSocket,
     })
   ),
 
-  // Send a datagram to a specific address.
-  // Returns the number of bytes sent.
+  /// Send a datagram to a specific address.
+  /// Returns the number of bytes sent.
   send_to : (fn(self: Self, data: ArrayList(u8), addr: SocketAddr, using(io : IO)) -> Impl(Future(i32, IO, Exception)))({
     fd := self._fd;
     io.async((using(io : IO, exn : Exception)) => {
@@ -101,8 +103,8 @@ impl(UdpSocket,
     })
   }),
 
-  // Receive a datagram.
-  // Returns the number of bytes received.
+  /// Receive a datagram into the provided buffer.
+  /// Returns the number of bytes received.
   recv : (fn(self: Self, buf: *(u8), size: usize, using(io : IO)) -> Impl(Future(i32, IO, Exception)))({
     fd := self._fd;
     io.async((using(io : IO, exn : Exception)) => {
@@ -111,8 +113,8 @@ impl(UdpSocket,
     })
   }),
 
-  // Receive a datagram and get the source address.
-  // Returns the number of bytes received.
+  /// Receive a datagram and retrieve the sender's address.
+  /// Returns the number of bytes received.
   recv_from : (fn(self: Self, buf: *(u8), size: usize, src_addr: *(u8), src_addr_len: *(u32), using(io : IO)) -> Impl(Future(i32, IO, Exception)))({
     fd := self._fd;
     io.async((using(io : IO, exn : Exception)) => {
@@ -121,7 +123,7 @@ impl(UdpSocket,
     })
   }),
 
-  // Send data on a connected socket (after connect()).
+  /// Send data on a connected socket (requires prior connect).
   send : (fn(self: Self, data: ArrayList(u8), using(io : IO)) -> Impl(Future(i32, IO, Exception)))({
     fd := self._fd;
     io.async((using(io : IO, exn : Exception)) => {
@@ -130,7 +132,7 @@ impl(UdpSocket,
     })
   }),
 
-  // Close the socket.
+  /// Close the socket.
   close : (fn(self: Self, using(io : IO)) -> Impl(Future(unit, IO, Exception)))({
     fd := self._fd;
     io.async((using(io : IO, exn : Exception)) => {
@@ -148,7 +150,7 @@ impl(UdpSocket,
     })
   }),
 
-  // Enable/disable SO_BROADCAST.
+  /// Enable or disable SO_BROADCAST on the socket.
   set_broadcast : (fn(self: Self, enabled: bool, using(io : IO)) -> Impl(Future(unit, IO, Exception)))({
     fd := self._fd;
     io.async((using(io : IO, exn : Exception)) => {
@@ -162,12 +164,12 @@ impl(UdpSocket,
     })
   }),
 
-  // Get the local address.
+  /// Get the local address this socket is bound to.
   local_addr : (fn(self: Self) -> SocketAddr)(
     self._local_addr
   ),
 
-  // Get the file descriptor.
+  /// Get the underlying file descriptor.
   fd : (fn(self: Self) -> i32)(
     self._fd
   )

package/std/os/env.yo

@@ -1,12 +1,15 @@
-// std/os/env.yo - Environment directory utilities
-//
-// Provides platform-aware paths for home, config, cache, and temp directories.
-//
-// Example:
-//   { home_dir, temp_dir } :: import "std/os/env";
-//
-//   home := home_dir();
-//   tmp  := temp_dir();
+//! Environment directory utilities.
+//!
+//! Provides platform-aware paths for home, config, cache, and temp directories.
+//!
+//! # Example
+//!
+//! ```rust
+//! { home_dir, temp_dir } :: import "std/os/env";
+//!
+//! home := home_dir();
+//! tmp  := temp_dir();
+//! ```
 
 open import "../string";
 { platform, Platform, env } :: import "../process";
@@ -15,7 +18,7 @@ open import "../string";
 // Directory helpers
 // ============================================================================
 
-// Return the current user's home directory, or .None if unavailable.
+/// Return the current user's home directory, or `.None` if unavailable.
 home_dir :: (fn() -> Option(String))(
   cond(
     (platform == Platform.Windows) => match(env.get(`USERPROFILE`),
@@ -32,9 +35,10 @@ home_dir :: (fn() -> Option(String))(
   )
 );
 
-// Return the user-specific configuration directory.
-//   Linux/macOS: $XDG_CONFIG_HOME or $HOME/.config
-//   Windows:     %APPDATA%
+/// Return the user-specific configuration directory.
+///
+/// - Linux/macOS: `$XDG_CONFIG_HOME` or `$HOME/.config`
+/// - Windows: `%APPDATA%`
 config_dir :: (fn() -> Option(String))(
   cond(
     (platform == Platform.Windows) => env.get(`APPDATA`),
@@ -48,10 +52,11 @@ config_dir :: (fn() -> Option(String))(
   )
 );
 
-// Return the user-specific cache directory.
-//   Linux:   $XDG_CACHE_HOME or $HOME/.cache
-//   macOS:   $HOME/Library/Caches
-//   Windows: %LOCALAPPDATA%
+/// Return the user-specific cache directory.
+///
+/// - Linux: `$XDG_CACHE_HOME` or `$HOME/.cache`
+/// - macOS: `$HOME/Library/Caches`
+/// - Windows: `%LOCALAPPDATA%`
 cache_dir :: (fn() -> Option(String))(
   cond(
     (platform == Platform.Windows) => env.get(`LOCALAPPDATA`),
@@ -69,7 +74,7 @@ cache_dir :: (fn() -> Option(String))(
   )
 );
 
-// Return the system temporary directory.
+/// Return the system temporary directory.
 temp_dir :: (fn() -> String)(
   cond(
     (platform == Platform.Windows) => match(env.get(`TEMP`),

package/std/os/signal.yo

@@ -1,12 +1,15 @@
-// std/os/signal.yo - High-level signal handling
-//
-// Wraps std/sys/signal with typed Signal enum values.
-//
-// Example:
-//   { on_signal, off_signal, Signal, SignalHandler } :: import "std/os/signal";
-//
-//   handler :: (fn(data: *(u8)) -> unit)({ println("Caught SIGINT"); });
-//   on_signal(.Interrupt, handler);
+//! High-level signal handling.
+//!
+//! Wraps `std/sys/signal` with a typed `Signal` enum.
+//!
+//! # Example
+//!
+//! ```rust
+//! { on_signal, off_signal, Signal, SignalHandler } :: import "std/os/signal";
+//!
+//! handler :: (fn(data: *(u8)) -> unit)({ println("Caught SIGINT"); });
+//! on_signal(.Interrupt, handler);
+//! ```
 
 { IOError } :: import "../sys/errors";
 {
@@ -19,15 +22,24 @@
 // Signal enum
 // ============================================================================
 
+/// Portable signal identifiers.
 Signal :: enum(
-  Interrupt,   // SIGINT  (Ctrl-C)
-  Terminate,   // SIGTERM
-  Hangup,      // SIGHUP
-  User1,       // SIGUSR1
-  User2,       // SIGUSR2
-  Pipe,        // SIGPIPE
-  Alarm,       // SIGALRM
-  Child        // SIGCHLD
+  /// SIGINT — interrupt from keyboard (Ctrl-C).
+  Interrupt,
+  /// SIGTERM — termination request.
+  Terminate,
+  /// SIGHUP — terminal hangup.
+  Hangup,
+  /// SIGUSR1 — user-defined signal 1.
+  User1,
+  /// SIGUSR2 — user-defined signal 2.
+  User2,
+  /// SIGPIPE — broken pipe.
+  Pipe,
+  /// SIGALRM — timer alarm.
+  Alarm,
+  /// SIGCHLD — child process status change.
+  Child
 );
 
 export Signal;
@@ -73,7 +85,7 @@ _signal_num :: (fn(sig: Signal) -> i32)(
 // on_signal / off_signal
 // ============================================================================
 
-// Register a handler for the given signal.
+/// Register a handler for the given signal.
 on_signal :: (fn(sig: Signal, handler: SignalHandler, using(exn : Exception)) -> unit)({
   num := _signal_num(sig);
   r   := _on_signal(num, handler);
@@ -85,7 +97,7 @@ on_signal :: (fn(sig: Signal, handler: SignalHandler, using(exn : Exception)) ->
   );
 });
 
-// Remove the handler for the given signal.
+/// Remove the handler for the given signal.
 off_signal :: (fn(sig: Signal, using(exn : Exception)) -> unit)({
   num := _signal_num(sig);
   r   := _off_signal(num);