From 9a8d4feedd2ba5873bbaacfbcd1be023901b02e1 Mon Sep 17 00:00:00 2001
From: Andrew Noyes <andrew@weaselab.dev>
Date: Thu, 11 Sep 2025 13:54:00 -0400
Subject: [PATCH] Add documentation

---
 src/reference.hpp | 86 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 78 insertions(+), 8 deletions(-)

diff --git a/src/reference.hpp b/src/reference.hpp
index e9bedb7..53d32d6 100644
--- a/src/reference.hpp
+++ b/src/reference.hpp
@@ -7,15 +7,28 @@
 #include <cstdlib>
 
 /**
- * @brief Thread-safe reference counting abstraction with shared/weak pointer
- * semantics
+ * @brief High-performance thread-safe reference counting system
  *
- * TODO: Implement custom reference counting system with:
+ * This library provides custom smart pointers with shared/weak semantics,
+ * designed for better performance than std::shared_ptr/weak_ptr.
+ *
+ * Key features:
  * - Thread-safe reference counting using atomic operations
- * - Weak reference support to break circular dependencies
- * - Move semantics for efficient transfers
- * - Custom deleter support
- * - Zero-overhead when not using weak references
+ * - Weak references to break circular dependencies
+ * - Single allocation for better cache locality
+ * - Optimized for copy/move operations
+ * - Compatible with std::shared_ptr semantics
+ *
+ * Basic usage:
+ * @code
+ * auto obj = make_ref<MyClass>(args...);     // Create managed object
+ * auto copy = obj;                           // Copy (thread-safe)
+ * WeakRef<MyClass> weak = obj;               // Create weak reference
+ * auto locked = weak.lock();                 // Try to promote to strong
+ * @endcode
+ *
+ * Thread safety: All operations are thread-safe. Multiple threads can
+ * safely copy, move, and destroy references to the same object.
  */
 
 namespace detail {
@@ -61,6 +74,31 @@ struct ControlBlock {
 };
 } // namespace detail
 
+/**
+ * @brief Strong reference to a shared object (similar to std::shared_ptr)
+ *
+ * Ref<T> manages shared ownership of an object. The object is automatically
+ * destroyed when the last Ref pointing to it is destroyed.
+ *
+ * Usage:
+ * - Use make_ref<T>() to create new objects
+ * - Copy/assign to share ownership
+ * - Use get(), operator*, operator-> to access the object
+ * - Use operator bool() to check if valid
+ * - Use reset() to release ownership
+ *
+ * Limitations compared to std::shared_ptr:
+ * - Cannot take ownership of raw pointers
+ * - Objects can only be created via make_ref<T>() for proper memory layout
+ * - No custom deleter support
+ * - No enable_shared_from_this / shared_from_this() integration
+ * - No aliasing constructor (sharing ownership with different pointer)
+ * - No array support (Ref<T[]>)
+ * - No atomic operations (atomic_load, atomic_store, etc.)
+ *
+ * Thread safety: All operations are thread-safe. The managed object
+ * itself is NOT automatically thread-safe.
+ */
 template <typename T> struct Ref {
   /**
    * @brief Get raw pointer to managed object
@@ -197,6 +235,22 @@ private:
   template <typename U> friend struct WeakRef;
 };
 
+/**
+ * @brief Weak reference to a shared object (similar to std::weak_ptr)
+ *
+ * WeakRef<T> holds a non-owning reference to an object managed by Ref<T>.
+ * It can be used to break circular dependencies and safely observe objects
+ * that might be destroyed by other threads.
+ *
+ * Usage:
+ * - Create from Ref<T> to observe without owning
+ * - Use lock() to attempt promotion to Ref<T>
+ * - Returns empty Ref<T> if object was already destroyed
+ * - Use reset() to stop observing
+ *
+ * Thread safety: All operations are thread-safe. The observed object
+ * may be destroyed by other threads at any time.
+ */
 template <typename T> struct WeakRef {
   /**
    * @brief Attempt to promote WeakRef to Ref
@@ -342,7 +396,23 @@ private:
 };
 
 /**
- * @brief Create a new Ref with object constructed in-place after control block
+ * @brief Create a new managed object wrapped in Ref<T>
+ *
+ * This is the only way to create Ref<T> objects. It performs a single
+ * allocation for both the control block and object, improving cache locality.
+ *
+ * @tparam T Type of object to create
+ * @tparam Args Types of constructor arguments
+ * @param args Arguments forwarded to T's constructor
+ * @return Ref<T> managing the newly created object
+ *
+ * Example:
+ * @code
+ * auto obj = make_ref<MyClass>(arg1, arg2);
+ * auto empty_vec = make_ref<std::vector<int>>();
+ * @endcode
+ *
+ * Thread safety: Safe to call from multiple threads simultaneously.
  */
 template <typename T, typename... Args> Ref<T> make_ref(Args &&...args) {
   constexpr size_t cb_size = sizeof(detail::ControlBlock);