style: align layout and ownership documentation

std/fs/fs.hon

@@ -20,17 +20,21 @@ Entry :: struct {
     kind Kind
 }
 
+#! returns caller-owned zero-terminated storage; release it with mem.free using the same allocator.
 @hide:file
 terminated proc(allocator mem.Allocator, text []u8) []mut u8 ! Error {
     if (text.len == 0 or text.len == maxval!(usize)) return .invalid_path
-    for (text) |byte| if (byte == 0) return .invalid_path
+    for (text) |byte| {
+        if (byte == 0) return .invalid_path
+    }
     bytes :: try mem.alloc(u8, allocator, text.len + 1)
     memcopy!(bytes[..text.len], text)
     bytes[text.len] = 0
     return bytes
 }
 
-#! returns an owned absolute path with symlinks resolved; free it with the same allocator.
+#! returns an owned absolute path with symlinks resolved; release it with mem.free using the same allocator.
+#! temporary path storage uses `allocator` and is released before returning.
 canonical proc(allocator mem.Allocator, path []u8) []mut u8 ! Error {
     input :: try terminated(allocator, path)
     defer mem.free(allocator, input)
@@ -49,6 +53,7 @@ canonical proc(allocator mem.Allocator, path []u8) []mut u8 ! Error {
 }
 
 #! follows symlinks; nonexistent paths (including dangling links) return missing.
+#! temporary path storage uses `allocator` and is released before returning.
 kind proc(allocator mem.Allocator, path []u8) Kind ! Error {
     input :: try terminated(allocator, path)
     defer mem.free(allocator, input)
@@ -69,7 +74,9 @@ exists proc(allocator mem.Allocator, path []u8) bool ! Error {
     return (try kind(allocator, path)) != .missing
 }
 
-#! opens an owned directory handle; path is borrowed only during this call.
+#! opens an owned directory handle; `path` is borrowed only during this call.
+#! temporary path storage uses `allocator` and is released before returning.
+#! release the returned handle with close_directory.
 open_directory proc(allocator mem.Allocator, path []u8) Directory ! Error {
     input :: try terminated(allocator, path)
     defer mem.free(allocator, input)
@@ -119,9 +126,10 @@ close_directory proc(directory @mut Directory) void ! Error {
     if (c.closedir(handle) != 0) return .directory_failed
 }
 
-#! reads a regular file through runtime IO, accepting at most maximum bytes.
+#! reads a regular file through runtime IO, accepting at most `maximum` bytes.
 #! follows symlinks and rejects devices/FIFOs before opening; metadata uses the host filesystem.
-#! returned storage belongs to the caller; release with arraylist.deinit. all errors close the file.
+#! returned storage belongs to the caller and retains `allocator`; release with arraylist.deinit. all errors close the file.
+#! temporary path storage uses `allocator` and is released before returning.
 read_file proc(
     allocator mem.Allocator,
     runtime io.Io,

std/mem/mem.hon

@@ -26,7 +26,8 @@ raw_alloc proc(
 }
 
 #! resize caller-owned storage with its original allocator and alignment.
-#! on allocation failure with nonzero `new_size`, original storage remains caller-owned; release the result with raw_free.
+#! on allocation failure with nonzero `new_size`, original storage remains caller-owned.
+#! release returned storage with raw_free using the same allocator and alignment, with `new_size` as its size.
 raw_realloc proc(
     allocator Allocator,
     memory ?*mut u8,
@@ -49,7 +50,9 @@ raw_free proc(
 
 eql proc($T type, left, right []T) bool {
     if (left.len != right.len) return false
-    for (0..left.len) |i| if (left[i] != right[i]) return false
+    for (0..left.len) |i| {
+        if (left[i] != right[i]) return false
+    }
     return true
 }
 

std/process/process.hon

@@ -19,7 +19,7 @@ RunError :: enum {
 }
 
 #! run a program synchronously without a shell, searching PATH for `arguments[0]`.
-#! arguments and zero-terminated strings are borrowed until this call returns.
+#! `arguments` and zero-terminated strings are borrowed until this call returns.
 #! an empty argument vector, empty executable name, or embedded NUL is invalid.
 #! the child inherits the current environment and stdin/stdout/stderr.
 #! temporary argument descriptors use `allocator` and are freed on every return.
@@ -28,7 +28,9 @@ run proc(allocator mem.Allocator, arguments [][;0]u8) i32 ! (mem.AllocError | Ru
     if (arguments.len == 0) return .invalid_arguments
     if (arguments[0].len == 0) return .invalid_arguments
     for arguments |argument| {
-        for (argument) |byte| if (byte == 0) return .invalid_arguments
+        for (argument) |byte| {
+            if (byte == 0) return .invalid_arguments
+        }
     }
     if (arguments.len == maxval!(usize)) return .out_of_memory
 
@@ -61,6 +63,6 @@ run proc(allocator mem.Allocator, arguments [][;0]u8) i32 ! (mem.AllocError | Ru
         signal :: status[0] & 127
         if (signal == 0) return i32(divtrunc!(status[0], 256) & 255)
         if (signal != 127) return i32(128 + signal)
-        # A traced child can report a stop even without WUNTRACED; wait for termination.
+        # a traced child can report a stop even without WUNTRACED; wait for termination.
     }
 }

std/strconv/strconv.hon

@@ -58,7 +58,9 @@ parse_float proc(allocator mem.Allocator, text []u8) f64 ! (mem.AllocError | Par
         magnitude >= u64(9218868437227405312)
         or (magnitude == 0 and nonzero)
         or (range_error and magnitude >= u64(4607182418800017408))
-    ) return .out_of_range
+    ) {
+        return .out_of_range
+    }
     return value
 }
 

std/strmap/strmap.hon

@@ -31,8 +31,10 @@ init proc($V type, $N usize, $entries [N]Pair(V)) StaticStringMap(V) {
             compile_error!("static string map key is too long")
         }
 
-        for (0..i) |prior| if mem.eql(u8, entry.0, entries[prior].0) {
-            compile_error!("duplicate static string map key")
+        for (0..i) |prior| {
+            if mem.eql(u8, entry.0, entries[prior].0) {
+                compile_error!("duplicate static string map key")
+            }
         }
 
         keys[i] = entry.0