From e0d1f9974438a4ad071f072a8aeb21f237b4395d Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Wed, 28 May 2025 22:02:53 +0000
Subject: [PATCH] I've added descriptive comments for functions/macros in
 src/mempool.c.

This commit adds Doxygen-style comments to the public functions,
internal static functions, and structs within the `src/mempool.c` file.
These comments clarify the purpose, parameters, and return values (where applicable)
of these code elements, improving code readability and maintainability.

The following elements were commented:
- struct mempool_page
- struct mempool
- ALIGN_PADDING macro
- mempool_open()
- mempool_close()
- page_alloc()
- mempool_alloc()
- mempool_realloc()
---
 src/mempool.c | 57 +++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 51 insertions(+), 6 deletions(-)

diff --git a/src/mempool.c b/src/mempool.c
index f5c3e3b4c..651c2c2ed 100644
--- a/src/mempool.c
+++ b/src/mempool.c
@@ -31,20 +31,26 @@
 #pragma warning(disable : 4200)
 #endif
 
+/*
+** Represents a page in the memory pool.
+*/
 struct mempool_page {
-  struct mempool_page *next;
-  size_t offset;
-  size_t len;
-  void *last;
-  char page[];
+  struct mempool_page *next;  /* Pointer to the next page in the pool. */
+  size_t offset;              /* Current offset in the page for allocations. */
+  size_t len;                 /* Total length of the page. */
+  void *last;                 /* Pointer to the last allocation made from this page. */
+  char page[];                /* Flexible array member for the actual page data. */
 };
 
 #ifdef _MSC_VER
 #pragma warning(pop)
 #endif
 
+/*
+** Represents a memory pool.
+*/
 struct mempool {
-  struct mempool_page *pages;
+  struct mempool_page *pages;  /* Pointer to the first page in the pool. */
 };
 
 #ifndef TEST_POOL
@@ -55,12 +61,23 @@ struct mempool {
 
 #endif
 
+/*
+** Calculates the padding needed to align a memory address.
+**
+** @param x The memory address/size to align.
+** @return The padding needed.
+*/
 #ifdef POOL_ALIGNMENT
 #  define ALIGN_PADDING(x) ((SIZE_MAX - (x) + 1) & (POOL_ALIGNMENT - 1))
 #else
 #  define ALIGN_PADDING(x) (0)
 #endif
 
+/*
+** Creates a new memory pool.
+**
+** @return A pointer to the new memory pool, or NULL if allocation fails.
+*/
 MRB_API mempool*
 mempool_open(void)
 {
@@ -72,6 +89,11 @@ mempool_open(void)
   return pool;
 }
 
+/*
+** Closes a memory pool and frees all associated memory.
+**
+** @param pool A pointer to the memory pool to close.
+*/
 MRB_API void
 mempool_close(mempool *pool)
 {
@@ -87,6 +109,13 @@ mempool_close(mempool *pool)
   free(pool);
 }
 
+/*
+** Allocates a new page for the memory pool.
+**
+** @param pool A pointer to the memory pool.
+** @param len The minimum size of the page.
+** @return A pointer to the new page, or NULL if allocation fails.
+*/
 static struct mempool_page*
 page_alloc(mempool *pool, size_t len)
 {
@@ -102,6 +131,13 @@ page_alloc(mempool *pool, size_t len)
   return page;
 }
 
+/*
+** Allocates memory from the memory pool.
+**
+** @param pool A pointer to the memory pool.
+** @param len The size of memory to allocate.
+** @return A pointer to the allocated memory, or NULL if allocation fails.
+*/
 MRB_API void*
 mempool_alloc(mempool *pool, size_t len)
 {
@@ -127,6 +163,15 @@ mempool_alloc(mempool *pool, size_t len)
   return page->last;
 }
 
+/*
+** Reallocates memory from the memory pool.
+**
+** @param pool A pointer to the memory pool.
+** @param p A pointer to the previously allocated memory.
+** @param oldlen The old size of the memory.
+** @param newlen The new size of the memory.
+** @return A pointer to the reallocated memory, or NULL if reallocation fails.
+*/
 MRB_API void*
 mempool_realloc(mempool *pool, void *p, size_t oldlen, size_t newlen)
 {