diff --git a/src/arena_allocator.hpp b/src/arena_allocator.hpp
index 7821f17..3142754 100644
--- a/src/arena_allocator.hpp
+++ b/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) {
diff --git a/src/commit_request.hpp b/src/commit_request.hpp
index 77dc7d7..49db846 100644
--- a/src/commit_request.hpp
+++ b/src/commit_request.hpp
@@ -49,7 +49,7 @@ class CommitRequest {
   };
 
   /**
-   * @brief Represents an operation in a commit request.
+   * @brief Internal state for parsing an operation during JSON processing.
    */
   struct OperationParseState {
     Operation::Type type;
@@ -142,8 +142,7 @@ private:
 
 public:
   /**
-   * @brief Construct a new CommitRequest with the given initial arena size.
-   * @param arena_size Initial size for the arena allocator
+   * @brief Construct a new CommitRequest with default arena size.
    */
   explicit CommitRequest()
       : arena_(), preconditions_(ArenaStlAllocator<Precondition>(&arena_)),
@@ -198,7 +197,8 @@ public:
 
   /**
    * @brief Parse a JSON string into a CommitRequest object (one-shot parsing).
-   * @param json_str The JSON string to parse
+   * @param data Pointer to the JSON data buffer
+   * @param len Length of the data in bytes
    * @return true if parsing succeeded, false otherwise
    */
   bool parse_json(char *data, size_t len);