authorgravatar for mason@gamesbymason.comMason Remaley <mason@gamesbymason.com> 2026-07-20 00:59:31-07:00
committergravatar for mason@gamesbymason.comMason Remaley <mason@gamesbymason.com> 2026-09-26 12:35:38-07:00
loge3a0e02ef28c96b9fe02fe564a18d44f767036b9
treeebe092313c72d0dafa274d01b1205266df88e0ae
parent5f457157573edbd99c9e685892b8f81c49cf5967

Clean up doc comments

2 files changed, 14 insertions(+), 13 deletions(-)

lib/std/mem/Allocator.zig-1
......@@ -196,7 +196,6 @@ pub inline fn createAdvancedWithRetAddr(
196196 return ptr;
197197}
198198
199
200199/// `ptr` should be the return value of `create`, or otherwise
201200/// have the same address and alignment property.
202201pub fn destroy(self: Allocator, ptr: anytype) void {
lib/std/zon/parse.zig+14-12
......@@ -1,11 +1,10 @@
1//! The simplest way to parse ZON at runtime is to use `fromSlice`/`fromSliceAlloc`.
1//! Use `fromSlice`/`fromSliceAlloc` to parse a ZON string into a Zig value. Human readable errors
2//! are written to an out parameter.
23//!
3//! Parsing from individual Zoir nodes is also available:
4//! * `fromZoir`/`fromZoirAlloc`
4//! If your data is already available in tree form, consider `fromZoir`/`fromZoirAlloc`.
55//!
6//! To update an existing values, see the `updateFrom*` variants. To get human readable errors, use
7//! the `errors` option. For lower level control over parsing, see `std.zig.Zoir`. For importing ZON
8//! at compile time, use `@import`.
6//! To parse into an existing value, see the `updateFrom*` variants. For lower level control over
7//! parsing, see `std.zig.ZonGen`. For importing ZON at compile time, use `@import`.
98
109const std = @import("std");
1110const Allocator = std.mem.Allocator;
......@@ -91,7 +90,8 @@ pub const Error = struct {
9190 };
9291};
9392
94/// Errors encountered while parsing ZON.
93/// Errors encountered while parsing ZON. Consider logging this using the default format method to
94/// provide users with feedback on the failure.
9595pub const Errors = struct {
9696 arena: Allocator,
9797 list: std.ArrayList(Error),
......@@ -160,9 +160,11 @@ pub fn fromSlice(T: type, options: FromSliceOptions) error{ OutOfMemory, ParseZo
160160 });
161161}
162162
163/// Similar to `fromSlice`, but updates an existing value `current`. Fields not specified by ZON are
164/// left at their current values. Pointers are replaced with new values not mutated in place. On
165/// failure, values that were updated prior to the failure are left updated.
163/// Similar to `fromSlice`, but updates `value` in place which is assumed to hold a valid value. Any
164/// unspecified fields are left unchanged.
165///
166/// Untagged unions and slices are replaced in their entiredy. If an error occurs while parsing,
167/// `value` remains valid but may be partially updated.
166168pub fn updateFromSlice(
167169 T: type,
168170 value: *T,
......@@ -181,7 +183,7 @@ pub fn updateFromSlice(
181183pub const FromSliceAllocOptions = struct {
182184 /// Used for scratch allocations.
183185 gpa: Allocator,
184 /// Owns the result.
186 /// Used for any allocations required by the out type.
185187 arena: Allocator,
186188 /// The ZON source to parse.
187189 source: [:0]const u8,
......@@ -303,7 +305,7 @@ pub fn updateFromZoir(
303305}
304306
305307pub const FromZoirAllocOptions = struct {
306 /// Owns the result.
308 /// Used for any allocations required by the out type.
307309 arena: Allocator,
308310 /// The AST for this ZON value.
309311 ast: *const Ast,