docs: document arena allocator

furlang/include/furlang/arena.hpp

@@ -8,6 +8,9 @@
 
 namespace furlang {
 
+/**
+ * @brief An arena (region) allocator implementation.
+ */
 class arena {
 private:
     struct region {
@@ -23,14 +26,35 @@ private:
         std::size_t free() const { return capacity - used; }
     };
 public:
+    /**
+     * @brief Construct a new arena.
+     *
+     * @param minCapacity Minimal capacity of a single region in words.
+     */
     arena(std::size_t minCapacity = 4 * 1024ULL);
     ~arena();
 
+    /**
+     * @brief Move constructor
+     */
     arena(arena&& other) noexcept;
+
     arena(const arena&) = delete;
+
+    /**
+     * @brief Move constructor
+     */
     arena& operator=(arena&& other) noexcept;
+
     arena& operator=(const arena&) = delete;
 public:
+    /**
+     * @brief Allocates and default constructs objects.
+     *
+     * @tparam T Type of the objects.
+     * @param count How many objects to allocate.
+     * @return A pointer to the allocated objects.
+     */
     template <typename T, typename = std::enable_if_t<std::is_default_constructible_v<T>>>
     T* allocate(std::size_t count) {
         T* allocated = reinterpret_cast<T*>(allocate(sizeof(T), count));
@@ -40,6 +64,13 @@ public:
         return allocated;
     }
 
+    /**
+     * @brief Allocates and constructs an object.
+     *
+     * @tparam T Type of the object.
+     * @param args Arguments passed to the object's constructor.
+     * @return A pointer to the allocated object.
+     */
     template <typename T, typename... Args, typename = std::enable_if_t<std::is_constructible_v<T, Args...>>>
     T* allocate(Args&&... args) {
         T* allocated = reinterpret_cast<T*>(allocate(sizeof(T), 1));
@@ -47,12 +78,25 @@ public:
         return allocated;
     }
 
+    /**
+     * @brief Allocates and constructs an object.
+     *
+     * @tparam T Type of the object.
+     * @param args Arguments passed to the object's constructor.
+     * @return A shared pointer to the allocated object.
+     */
     template <typename T, typename... Args>
     std::shared_ptr<T> allocate_shared(Args&&... args) {
         T* allocated = allocate<T>(std::forward<Args>(args)...);
         return std::shared_ptr<T>(allocated, [](T* object) { object->~T(); });
     }
 
+    /**
+     * @brief Resets the arena.
+     *
+     * Resets occupied size of regions. Using previously allocated pointers after calling this function is
+     * undefined-behaviour.
+     */
     void reset();
 private:
     void* allocate(std::size_t size, std::size_t count);

furlang/include/furlang/furlang.hpp

@@ -0,0 +1,11 @@
+#ifndef FURLANG_HPP
+#define FURLANG_HPP
+
+#include "furlang/result.hpp" // IWYU pragma: export
+
+/**
+ * @brief The common furlang library.
+ */
+namespace furlang {}
+
+#endif // FURLANG_HPP