zig

commit e25541549852c8dcf4acbcc1a3f3d7ef4bcef9d7 (tree)
parent 88e50b30c3c929761f2ae1a924b96f8bc7548b84
Author: Andrew Kelley <andrew@ziglang.org>
Date:   Thu, 10 Jul 2025 13:14:55 -0700

std: add some missing doc comments

Diffstat:
M
lib/std/Io/Reader.zig
 | 
9
+++++++++
M
lib/std/Io/Writer.zig
 | 
5
+++++

2 files changed, 14 insertions(+), 0 deletions(-)
diff --git a/lib/std/Io/Reader.zig b/lib/std/Io/Reader.zig
@@ -840,6 +840,9 @@ pub fn peekDelimiterExclusive(r: *Reader, delimiter: u8) DelimiterError![]u8 {
 /// Returns number of bytes streamed, which may be zero, or error.EndOfStream
 /// if the delimiter was not found.
 ///
+/// Asserts buffer capacity of at least one. This function performs better with
+/// larger buffers.
+///
 /// See also:
 /// * `streamDelimiterEnding`
 /// * `streamDelimiterLimit`
@@ -858,6 +861,9 @@ pub fn streamDelimiter(r: *Reader, w: *Writer, delimiter: u8) StreamError!usize 
 /// Returns number of bytes streamed, which may be zero. End of stream can be
 /// detected by checking if the next byte in the stream is the delimiter.
 ///
+/// Asserts buffer capacity of at least one. This function performs better with
+/// larger buffers.
+///
 /// See also:
 /// * `streamDelimiter`
 /// * `streamDelimiterLimit`
@@ -884,6 +890,9 @@ pub const StreamDelimiterLimitError = error{
 ///
 /// Returns number of bytes streamed, which may be zero. End of stream can be
 /// detected by checking if the next byte in the stream is the delimiter.
+///
+/// Asserts buffer capacity of at least one. This function performs better with
+/// larger buffers.
 pub fn streamDelimiterLimit(
     r: *Reader,
     w: *Writer,
diff --git a/lib/std/Io/Writer.zig b/lib/std/Io/Writer.zig
@@ -560,6 +560,10 @@ pub fn writeAllPreserve(w: *Writer, preserve_length: usize, bytes: []const u8) E
 /// A user type may be a `struct`, `vector`, `union` or `enum` type.
 ///
 /// To print literal curly braces, escape them by writing them twice, e.g. `{{` or `}}`.
+///
+/// Asserts `buffer` capacity of at least 2 if a union is printed. This
+/// requirement could be lifted by adjusting the code, but if you trigger that
+/// assertion it is a clue that you should probably be using a buffer.
 pub fn print(w: *Writer, comptime fmt: []const u8, args: anytype) Error!void {
     const ArgsType = @TypeOf(args);
     const args_type_info = @typeInfo(ArgsType);
@@ -930,6 +934,7 @@ pub fn printAddress(w: *Writer, value: anytype) Error!void {
     @compileError("cannot format non-pointer type " ++ @typeName(T) ++ " with * specifier");
 }
 
+/// Asserts `buffer` capacity of at least 2 if `value` is a union.
 pub fn printValue(
     w: *Writer,
     comptime fmt: []const u8,