Update docstrings

src/arena_allocator.hpp

@@ -227,7 +227,7 @@ public:
    * @param ptr Pointer to the existing allocation (must be from this allocator)
    * @param old_size Size of the existing allocation in bytes
    * @param new_size Desired new size in bytes
-   * @param alignment Required alignment (default: alignof(std::max_align_t))
+   * @param alignment Required alignment
    * @return Pointer to the reallocated memory (may be the same as ptr or
    * different)
    * @throws std::bad_alloc if memory allocation fails
@@ -240,9 +240,10 @@ public:
    *
    * ## Example:
    * ```cpp
-   * void* ptr = arena.allocate(100);
+   * void* ptr = arena.allocate_raw(100, alignof(int));
    * // ... use ptr ...
-   * ptr = arena.realloc_raw(ptr, 100, 200);  // May extend in place or copy
+   * ptr = arena.realloc_raw(ptr, 100, 200, alignof(int));  // May extend in
+   * place or copy
    * ```
    *
    * ## Safety Notes:
@@ -252,42 +253,17 @@ public:
    * - When copying to new location, uses the specified alignment
    */
   void *realloc_raw(void *ptr, uint32_t old_size, uint32_t new_size,
-                    uint32_t alignment = alignof(std::max_align_t));
+                    uint32_t alignment);
 
   /**
-   * @brief Reallocate memory, extending in place if possible or copying to a
-   * new location.
-   *
-   * This method provides realloc-like functionality for the arena allocator.
-   * If the given pointer was the last allocation and there's sufficient space
-   * in the current block to extend it, the allocation is grown in place.
-   * Otherwise, a new allocation is made and the old data is copied.
+   * @brief Type-safe version of realloc_raw for arrays of type T.
    *
    * @param ptr Pointer to the existing allocation (must be from this allocator)
-   * @param old_size Size of the existing allocation in T's
-   * @param new_size Desired new size in T's
+   * @param old_size Size of the existing allocation in number of T objects
+   * @param new_size Desired new size in number of T objects
    * @return Pointer to the reallocated memory (may be the same as ptr or
    * different)
-   * @throws std::bad_alloc if memory allocation fails
-   *
-   * ## Behavior:
-   * - If new_size == old_size, returns ptr unchanged
-   * - If new_size == 0, returns nullptr (no deallocation occurs)
-   * - If ptr is null, behaves like allocate(new_size, alignment)
-   * - If ptr was the last allocation and space exists, extends in place
-   *
-   * ## Example:
-   * ```cpp
-   * void* ptr = arena.allocate(100);
-   * // ... use ptr ...
-   * ptr = arena.realloc(ptr, 100, 200);  // May extend in place or copy
-   * ```
-   *
-   * ## Safety Notes:
-   * - The caller must provide the correct old_size - this is not tracked
-   * - The old pointer becomes invalid if a copy occurs
-   * - Like malloc/realloc, the contents beyond old_size are uninitialized
-   * - When copying to new location, uses the specified alignment
+   * @throws std::bad_alloc if memory allocation fails or size overflow occurs
    */
   template <typename T>
   T *realloc(T *ptr, uint32_t old_size, uint32_t new_size) {