From e3a0e02ef28c96b9fe02fe564a18d44f767036b9 Mon Sep 17 00:00:00 2001
From: Mason Remaley <mason@gamesbymason.com>
Date: Mon, 20 Jul 2026 00:59:31 -0700
Subject: [PATCH] Clean up doc comments

---
 lib/std/mem/Allocator.zig |  1 -
 lib/std/zon/parse.zig     | 26 ++++++++++++++------------
 2 files changed, 14 insertions(+), 13 deletions(-)

diff --git a/lib/std/mem/Allocator.zig b/lib/std/mem/Allocator.zig
index 43db84febd6f222ef617d48bb136fd46abee2f9d..be76c4982d1a2bd0284978ff6a57477097b570ca 100644
--- a/lib/std/mem/Allocator.zig
+++ b/lib/std/mem/Allocator.zig
@@ -196,7 +196,6 @@ pub inline fn createAdvancedWithRetAddr(
     return ptr;
 }
 
-
 /// `ptr` should be the return value of `create`, or otherwise
 /// have the same address and alignment property.
 pub fn destroy(self: Allocator, ptr: anytype) void {
diff --git a/lib/std/zon/parse.zig b/lib/std/zon/parse.zig
index 4585d111a842c7bc118c30d8e2b3da25324c33fc..3d6af24e713ee3254824beee03a03914be57c539 100644
--- a/lib/std/zon/parse.zig
+++ b/lib/std/zon/parse.zig
@@ -1,11 +1,10 @@
-//! The simplest way to parse ZON at runtime is to use `fromSlice`/`fromSliceAlloc`.
+//! Use `fromSlice`/`fromSliceAlloc` to parse a ZON string into a Zig value. Human readable errors
+//! are written to an out parameter.
 //!
-//! Parsing from individual Zoir nodes is also available:
-//! * `fromZoir`/`fromZoirAlloc`
+//! If your data is already available in tree form, consider `fromZoir`/`fromZoirAlloc`.
 //!
-//! To update an existing values, see the `updateFrom*` variants. To get human readable errors, use
-//! the `errors` option. For lower level control over parsing, see `std.zig.Zoir`. For importing ZON
-//! at compile time, use `@import`.
+//! To parse into an existing value, see the `updateFrom*` variants. For lower level control over
+//! parsing, see `std.zig.ZonGen`. For importing ZON at compile time, use `@import`.
 
 const std = @import("std");
 const Allocator = std.mem.Allocator;
@@ -91,7 +90,8 @@ pub const Error = struct {
     };
 };
 
-/// Errors encountered while parsing ZON.
+/// Errors encountered while parsing ZON. Consider logging this using the default format method to
+/// provide users with feedback on the failure.
 pub const Errors = struct {
     arena: Allocator,
     list: std.ArrayList(Error),
@@ -160,9 +160,11 @@ pub fn fromSlice(T: type, options: FromSliceOptions) error{ OutOfMemory, ParseZo
     });
 }
 
-/// Similar to `fromSlice`, but updates an existing value `current`. Fields not specified by ZON are
-/// left at their current values. Pointers are replaced with new values not mutated in place. On
-/// failure, values that were updated prior to the failure are left updated.
+/// Similar to `fromSlice`, but updates `value` in place which is assumed to hold a valid value. Any
+/// unspecified fields are left unchanged.
+///
+/// Untagged unions and slices are replaced in their entiredy. If an error occurs while parsing,
+/// `value` remains valid but may be partially updated.
 pub fn updateFromSlice(
     T: type,
     value: *T,
@@ -181,7 +183,7 @@ pub fn updateFromSlice(
 pub const FromSliceAllocOptions = struct {
     /// Used for scratch allocations.
     gpa: Allocator,
-    /// Owns the result.
+    /// Used for any allocations required by the out type.
     arena: Allocator,
     /// The ZON source to parse.
     source: [:0]const u8,
@@ -303,7 +305,7 @@ pub fn updateFromZoir(
 }
 
 pub const FromZoirAllocOptions = struct {
-    /// Owns the result.
+    /// Used for any allocations required by the out type.
     arena: Allocator,
     /// The AST for this ZON value.
     ast: *const Ast,
-- 
2.54.0