Simplify public headers more

src/arena_allocator.hpp

@@ -37,20 +37,10 @@
  *
  * ## Usage Examples:
  * ```cpp
- * // Basic allocation
  * ArenaAllocator arena(1024);
- * void* ptr = arena.allocate(100);
- *
- * // Construct trivially destructible objects in-place
+ * void* ptr = arena.allocate_raw(100);
  * int* num = arena.construct<int>(42);
- * MyPOD* obj = arena.construct<MyPOD>(arg1, arg2);  // If MyPOD is trivial
- *
- * // Track memory usage
- * size_t total = arena.total_allocated();
- * size_t used = arena.used_bytes();
- *
- * // Reset to reuse first block (frees others)
- * arena.reset();
+ * arena.reset(); // Reuse arena memory
  * ```
  *
  * ## Memory Management:
@@ -172,18 +162,7 @@ public:
    * - Respects alignment requirements with minimal padding
    * - Automatically creates new blocks when current block is exhausted
    *
-   * ## Example:
-   * ```cpp
-   * void* ptr1 = arena.allocate_raw(100);              // Default alignment
-   * void* ptr2 = arena.allocate_raw(64, 16);           // 16-byte aligned
-   * MyStruct* ptr3 = static_cast<MyStruct*>(
-   *     arena.allocate_raw(sizeof(MyStruct), alignof(MyStruct)));
-   * ```
-   *
-   * ## Performance Note:
-   * This method is kept inline in the header for maximum performance.
-   * The allocation path is extremely hot and inlining eliminates function
-   * call overhead, allowing the ~1ns allocation performance.
+   * @note This method is kept inline for maximum performance (~1ns allocation).
    */
   void *allocate_raw(uint32_t size,
                      size_t alignment = alignof(std::max_align_t)) {
@@ -239,13 +218,6 @@ public:
    * - 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_raw(100, alignof(int));
-   * // ... use ptr ...
-   * ptr = arena.realloc_raw(ptr, 100, 200, alignof(int));  // May extend in
-   * place or copy
-   * ```
    *
    * ## Safety Notes:
    * - The caller must provide the correct old_size - this is not tracked
@@ -292,13 +264,6 @@ public:
    * This prevents subtle bugs since destructors are never called for objects
    * constructed in the arena.
    *
-   * ## Example:
-   * ```cpp
-   * int* num = arena.construct<int>(42);                    // ✓ Trivially
-   * destructible MyPOD* pod = arena.construct<MyPOD>(arg1, arg2);       // ✓ If
-   * MyPOD is trivial std::string* str = arena.construct<std::string>("hi"); //
-   * ✗ Compile error!
-   * ```
    *
    * ## Note:
    * Objects constructed this way cannot be individually destroyed.
@@ -335,18 +300,6 @@ public:
    * This ensures consistency with the arena allocator's design where
    * destructors are never called.
    *
-   * ## Example:
-   * ```cpp
-   * // Allocate space for 100 integers
-   * int* numbers = arena.allocate<int>(100);
-   *
-   * // Allocate space for 50 POD structs
-   * MyPOD* objects = arena.allocate<MyPOD>(50);
-   *
-   * // Initialize some elements (no automatic construction)
-   * numbers[0] = 42;
-   * new (&objects[0]) MyPOD(arg1, arg2);
-   * ```
    *
    * ## Note:
    * This method only allocates memory - it does not construct objects.
@@ -383,12 +336,6 @@ public:
    * - Prevents memory leaks by freeing unused blocks
    * - Faster than destroying and recreating the allocator
    *
-   * ## Example:
-   * ```cpp
-   * arena.allocate(1000);  // Creates blocks
-   * arena.reset();         // Frees extra blocks, keeps first
-   * arena.allocate(100);   // Reuses first block
-   * ```
    */
   void reset();
 
@@ -429,6 +376,9 @@ public:
 
   /**
    * @brief Get the total number of blocks in the allocator.
+   *
+   * @note This function is primarily used for testing and debugging.
+   * It has O(n) complexity as it traverses the entire block chain.
    */
   size_t num_blocks() const {
     size_t result = 0;
@@ -438,88 +388,22 @@ public:
     return result;
   }
 
-  /**
-   * @brief Debug function to find all intra-arena pointers.
-   *
-   * Scans all used memory in the arena for 64-bit aligned values that could be
-   * pointers to locations within the arena itself. This is useful for
-   * understanding memory references and potential data structures.
-   *
-   * @return Vector of PointerInfo structs containing source and target
-   * addresses
-   */
-  struct PointerInfo {
-    const void *source_addr;    ///< Address where the pointer was found
-    size_t source_block_number; ///< Block number containing the source
-    size_t source_offset;       ///< Offset within the source block
-    const void *target_addr;    ///< Address the pointer points to
-    size_t target_block_number; ///< Block number containing the target
-    size_t target_offset;       ///< Offset within the target block
-
-    PointerInfo(const void *src, size_t src_block, size_t src_offset,
-                const void *target, size_t target_block, size_t target_offset)
-        : source_addr(src), source_block_number(src_block),
-          source_offset(src_offset), target_addr(target),
-          target_block_number(target_block), target_offset(target_offset) {}
-  };
-
-  std::vector<PointerInfo> find_intra_arena_pointers() const;
-
-  /**
-   * @brief Find which block and offset a given address belongs to.
-   *
-   * @param addr The address to locate within the arena
-   * @return PointerInfo with block number and offset, or invalid info if not
-   * found
-   */
-  struct AddressLocation {
-    size_t block_number;
-    size_t offset_in_block;
-    bool found;
-
-    AddressLocation() : block_number(0), offset_in_block(0), found(false) {}
-    AddressLocation(size_t block, size_t offset)
-        : block_number(block), offset_in_block(offset), found(true) {}
-  };
-
-  AddressLocation find_address_location(const void *addr) const;
-
   /**
    * @brief Debug function to visualize the arena's layout and contents.
    *
+   * @note This function is intended for testing, debugging, and development
+   * only. It should not be used in production code due to performance overhead.
+   *
    * Prints a detailed breakdown of all blocks, memory usage, and allocation
    * patterns. This is useful for understanding memory fragmentation and
    * allocation behavior during development and debugging.
    *
-   * Output includes:
-   * - Overall arena statistics (total allocated, used, blocks)
-   * - Per-block breakdown with sizes and usage
-   * - Memory utilization percentages
-   * - Block chain visualization
-   * - Optional memory content visualization
-   *
    * @param out Output stream to write debug information to (default: std::cout)
    * @param show_memory_map If true, shows a visual memory map of used/free
    * space
    * @param show_content If true, shows actual memory contents in hex and ASCII
    * @param content_limit Maximum bytes of content to show per block (default:
    * 256)
-   *
-   * ## Example Output:
-   * ```
-   * === Arena Debug Dump ===
-   * Total allocated: 3072 bytes across 2 blocks
-   * Currently used: 1500 bytes (48.8% utilization)
-   * Available in current: 572 bytes
-   *
-   * Block Chain (newest to oldest):
-   * Block #2: 2048 bytes [used: 572/2048 = 27.9%] <- current
-   * Block #1: 1024 bytes [used: 1024/1024 = 100.0%]
-   *
-   * Memory Contents:
-   * Block #2 (first 256 bytes):
-   * 0x0000: 48656c6c 6f20576f 726c6400 54657374  |Hello World.Test|
-   * ```
    */
   void debug_dump(std::ostream &out = std::cout, bool show_memory_map = false,
                   bool show_content = false, size_t content_limit = 256) const;