From 4f142b72f22d6ab141fbe181b52c59e9446b2f01 Mon Sep 17 00:00:00 2001
From: hl-valdemar <valdemar.lorenzen@icloud.com>
Date: Tue, 11 Aug 2026 22:36:22 +0200
Subject: [PATCH] improve std/mem doc comments

---
 std/mem/mem.hon | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/std/mem/mem.hon b/std/mem/mem.hon
index 1dc2c9f..7b0d41b 100644
--- a/std/mem/mem.hon
+++ b/std/mem/mem.hon
@@ -78,6 +78,7 @@ realloc proc($T type, allocator Allocator, memory []mut T, new_count usize) []mu
         old_memory = ptrcast!(u8, memory.ptr)
         old_size = memory.len * element_size
     }
+
     resized := raw_realloc(
         allocator,
         old_memory,
@@ -85,6 +86,7 @@ realloc proc($T type, allocator Allocator, memory []mut T, new_count usize) []mu
         new_count * element_size,
         alignof!(T),
     )
+
     if resized |bytes| {
         pointer *mut T :: ptrcast!(T, bytes)
         return pointer[..new_count]
@@ -105,7 +107,10 @@ free proc($T type, allocator Allocator, memory []T) void {
     )
 }
 
-#! get an empty slice of type `T` with `count` elements.
+#! create a slice backed by `empty_storage` without allocating.
+#! precondition: `count` must be 0 or `sizeof!(T)` must be 0; otherwise the slice
+#! exceeds its backing storage.
+@hide:file
 empty_slice proc($T type, count usize) []mut T {
     pointer *mut T :: ptrcast!(T, (&empty_storage).ptr)
     return pointer[..count]