From 3ed2ab6e2c18081d80961168a57155e6f31ac573 Mon Sep 17 00:00:00 2001
From: flysand7 <thebumboni@gmail.com>
Date: Sat, 14 Sep 2024 10:18:51 +1100
Subject: [PATCH] [mem]: Adjust the docs for calc_padding_with_header

---
 core/mem/alloc.odin |  3 +--
 core/mem/mem.odin   | 24 ++++++++++++++++++++----
 2 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/core/mem/alloc.odin b/core/mem/alloc.odin
index 5f65e9ebcf6..fac58daafef 100644
--- a/core/mem/alloc.odin
+++ b/core/mem/alloc.odin
@@ -1019,8 +1019,7 @@ Default resize procedure.
 
 When allocator does not support resize operation, but supports
 `.Alloc_Non_Zeroed` and `.Free`, this procedure is used to implement allocator's
-default behavior on
-resize.
+default behavior on resize.
 
 Unlike `default_resize_align` no new memory is being explicitly
 zero-initialized.
diff --git a/core/mem/mem.odin b/core/mem/mem.odin
index b57b18ffcb0..67ed56c39a0 100644
--- a/core/mem/mem.odin
+++ b/core/mem/mem.odin
@@ -644,10 +644,26 @@ align_formula :: proc "contextless" (size, align: int) -> int {
 }
 
 /*
-Calculate the padding after the pointer with a header.
-
-This procedure returns the next address, following `ptr` and `header_size`
-bytes of space that is aligned to a boundary specified by `align`.
+Calculate the padding for header preceding aligned data.
+
+This procedure returns the padding, following the specified pointer `ptr` that
+will be able to fit in a header of the size `header_size`, immediately
+preceding the memory region, aligned on a boundary specified by `align`. See
+the following diagram for a visual representation.
+
+        header size
+	    |<------>|
+	+---+--------+------------- - - -
+	    | HEADER |  DATA...
+	+---+--------+------------- - - -
+	^            ^
+	|<---------->|
+	|  padding   |
+	ptr          aligned ptr
+
+The function takes in `ptr` and `header_size`, as well as the required
+alignment for `DATA`. The return value of the function is the padding between
+`ptr` and `aligned_ptr` that will be able to fit the header.
 */
 @(require_results)
 calc_padding_with_header :: proc "contextless" (ptr: uintptr, align: uintptr, header_size: int) -> int {