kstd: improve vector documentation

1 files changed, 76 insertions, 27 deletions

diff --git a/libs/kstd/include/kstd/vector b/libs/kstd/include/kstd/vector
index a897b47..de5c059 100644
--- a/libs/kstd/include/kstd/vector
+++ b/libs/kstd/include/kstd/vector
@@ -17,27 +17,36 @@
 
 namespace kstd
 {
-  /**
-   * @brief Custom vector implementation mirroring the std::vector to allow for the usage of STL functionality with our
-   * custom memory management.
-   *
-   * @tparam T Element the vector instance should contain.
-   * @tparam Allocator The allocator to use when allocating new elements.
-   */
-  template<typename T, typename Allocator = kstd::allocator<T>>
+  //! A resizable, contiguous container.
+  //!
+  //! @tparam ValueType The type of values contained in this vector.
+  //! @tparam Allocator The type of allocator used for memory management by this container.
+  template<typename ValueType, typename Allocator = kstd::allocator<ValueType>>
   struct vector
   {
-    using value_type = T;                        ///< Type of the elements contained in the container.
-    using allocator_type = Allocator;            ///< Type of the allocator used by the container.
-    using size_type = std::size_t;               ///< Type of the size in the container.
-    using difference_type = std::ptrdiff_t;      ///< Type of the difference between two iterators.
-    using reference = value_type &;              ///< Type of reference to the elements.
-    using const_reference = value_type const &;  ///< Type of constant reference to the elements.
-    using pointer = value_type *;                ///< Type of pointer to the elements.
-    using const_pointer = value_type const *;    ///< Type of constant pointer to the elements.
-    using iterator = pointer;                    ///< Type of iterator to the elements.
-    using const_iterator = const_pointer;        ///< Type of constant iterator to the elements.
+    //! The type of the elements contained in this vector.
+    using value_type = ValueType;
+    //! The allocator used by this vector for memory management.
+    using allocator_type = Allocator;
+    //! The type of all sizes used in and with this vector.
+    using size_type = std::size_t;
+    //! The type of the difference between two iterators.
+    using difference_type = std::ptrdiff_t;
+    //! The type of references to elements in this vector.
+    using reference = value_type &;
+    //! The type of references to constant elements in this vector.
+    using const_reference = value_type const &;
+    //! The type of pointers to elements in this vector.
+    using pointer = value_type *;
+    //! The type of pointers to constant elements in this vector.
+    using const_pointer = value_type const *;
+    //! The type of iterators into this container.
+    using iterator = pointer;
+    //! The type of constant iterators into this container.
+    using const_iterator = const_pointer;
+    //! The type of reverse iterators into this container.
     using reverse_iterator = std::reverse_iterator<iterator>;
+    //! The type of constant reverse iterators into this container.
     using const_reverse_iterator = std::reverse_iterator<const_iterator>;
 
     //! Construct a new, empty vector.
@@ -114,7 +123,7 @@ namespace kstd
     //!
     template<typename Range>
       requires(std::ranges::input_range<Range> && std::ranges::sized_range<Range> &&
-               std::convertible_to<std::ranges::range_reference_t<Range>, T>)
+               std::convertible_to<std::ranges::range_reference_t<Range>, ValueType>)
     constexpr vector(kstd::from_range_t, Range && range, allocator_type const & allocator = allocator_type{})
         : m_allocator{allocator}
         , m_size{std::ranges::size(range)}
@@ -595,6 +604,9 @@ namespace kstd
     }
 
   private:
+    //! Use the allocator of this vector to allocate enough space for the given number of elements.
+    //!
+    //! @param count The number of elements to allocate space for.
     [[nodiscard]] constexpr auto allocate_n(std::size_t count) -> std::allocator_traits<allocator_type>::pointer
     {
       if (count)
@@ -604,13 +616,19 @@ namespace kstd
       return nullptr;
     }
 
+    //! Clear this vector and release it's memory.
     constexpr auto clear_and_deallocate() -> void
     {
       clear();
       deallocate();
     }
 
-    constexpr auto copy_elements(const_iterator from, iterator to, size_type count) -> void
+    //! Copy a number of elements from one storage location to another.
+    //!
+    //! @param from The start of the source range.
+    //! @param to The start of the target range.
+    //! @param count The number of element to copy.
+    constexpr auto static copy_elements(const_iterator from, iterator to, size_type count) -> void
     {
       for (auto i = 0uz; i < count; ++i)
       {
@@ -618,6 +636,7 @@ namespace kstd
       }
     }
 
+    //! Release the memory of this vector.
     constexpr auto deallocate()
     {
       std::allocator_traits<allocator_type>::deallocate(m_allocator, m_data, m_capacity);
@@ -626,14 +645,19 @@ namespace kstd
       m_data = nullptr;
     }
 
-    constexpr auto destroy_n(iterator begin, std::size_t count) -> void
+    //! Destroy a number of elements in this vector.
+    //!
+    //! @param first The start of the range of the elements to be destroyed.
+    //! @param count The number of elements to destroy.
+    constexpr auto destroy_n(iterator first, std::size_t count) -> void
     {
-      std::ranges::for_each(begin, begin + count, [&](auto & element) {
+      std::ranges::for_each(first, first + count, [&](auto & element) {
         std::allocator_traits<allocator_type>::destroy(m_allocator, std::addressof(element));
       });
     }
 
-    auto increase_capacity_if_full() -> void
+    //! Check if there is still room in this vector, and if not allocate more space.
+    constexpr auto increase_capacity_if_full() -> void
     {
       if (m_size == m_capacity)
       {
@@ -641,7 +665,12 @@ namespace kstd
       }
     }
 
-    constexpr auto move_elements(iterator from, iterator to, size_t count)
+    //! Move a number of elements from one storage location to another.
+    //!
+    //! @param from The start of the source range.
+    //! @param to The start of the target range.
+    //! @param count The number of element to copy.
+    constexpr auto static move_elements(iterator from, iterator to, size_t count)
     {
       for (auto i = 0uz; i < count; ++i)
       {
@@ -649,6 +678,9 @@ namespace kstd
       }
     }
 
+    //! Panic the kernel if the given index is out of bounds.
+    //!
+    //! @param index The index to check.
     constexpr auto panic_if_out_of_bounds(size_type index) const -> void
     {
       if (index >= m_size)
@@ -657,6 +689,11 @@ namespace kstd
       }
     }
 
+    //! Copy a number of elements from a source range into the uninitialized destination range inside this vector.
+    //!
+    //! @param from The start of the source range.
+    //! @param to The start of the target range inside this vector.
+    //! @param count The number of elements to copy
     constexpr auto uninitialized_copy_with_allocator(const_iterator from, iterator to, size_type count)
     {
       for (auto i = 0uz; i < count; ++i)
@@ -665,6 +702,11 @@ namespace kstd
       }
     }
 
+    //! Move a number of elements from a source range into the uninitialized destination range inside this vector.
+    //!
+    //! @param from The start of the source range.
+    //! @param to The start of the target range inside this vector.
+    //! @param count The number of elements to copy
     constexpr auto uninitialized_move_with_allocator(iterator from, iterator to, size_type count)
     {
       for (auto i = 0uz; i < count; ++i)
@@ -673,10 +715,17 @@ namespace kstd
       }
     }
 
+    //! The allocator used by this vector.
     [[no_unique_address]] allocator_type m_allocator{};
-    size_type m_size{};      ///< Amount of elements in the underlying data container
-    size_type m_capacity{};  ///< Amount of space for elements in the underlying data container
-    value_type * m_data{};   ///< Pointer to the first element in the underlying data container
+
+    //! The number of elements in this vector.
+    size_type m_size{};
+
+    //! The number of elements this vector has room for.
+    size_type m_capacity{};
+
+    //! The pointer to the start of the memory managed by this vector.
+    value_type * m_data{};
   };
 
 }  // namespace kstd