From ff4f2753e4eb1226c1b18a812ee6ff5ca914fe85 Mon Sep 17 00:00:00 2001
From: axel escalada <87334103+axlEscalada@users.noreply.github.com>
Date: Sat, 4 Jan 2025 10:45:12 -0300
Subject: [PATCH] Improve `first()` documentation for split iterators

* remove  from doc., add explicit info when panic

* match convention for assert documentation, avoiding to use panic here
---
 lib/std/mem.zig | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/lib/std/mem.zig b/lib/std/mem.zig
index 1f1e925f54..583f6eb00a 100644
--- a/lib/std/mem.zig
+++ b/lib/std/mem.zig
@@ -2903,9 +2903,10 @@ pub fn WindowIterator(comptime T: type) type {
 
         const Self = @This();
 
-        /// Returns a slice of the first window. This never fails.
+        /// Returns a slice of the first window.
         /// Call this only to get the first window and then use `next` to get
         /// all subsequent windows.
+        /// Asserts that iteration has not begun.
         pub fn first(self: *Self) []const T {
             assert(self.index.? == 0);
             return self.next().?;
@@ -3037,8 +3038,9 @@ pub fn SplitIterator(comptime T: type, comptime delimiter_type: DelimiterType) t
 
         const Self = @This();
 
-        /// Returns a slice of the first field. This never fails.
+        /// Returns a slice of the first field.
         /// Call this only to get the first field and then use `next` to get all subsequent fields.
+        /// Asserts that iteration has not begun.
         pub fn first(self: *Self) []const T {
             assert(self.index.? == 0);
             return self.next().?;
@@ -3101,8 +3103,9 @@ pub fn SplitBackwardsIterator(comptime T: type, comptime delimiter_type: Delimit
 
         const Self = @This();
 
-        /// Returns a slice of the first field. This never fails.
+        /// Returns a slice of the first field.
         /// Call this only to get the first field and then use `next` to get all subsequent fields.
+        /// Asserts that iteration has not begun.
         pub fn first(self: *Self) []const T {
             assert(self.index.? == self.buffer.len);
             return self.next().?;