1 files changed, 143 insertions, 0 deletions
diff --git a/src/vector.h b/src/vector.h
index b329192..271fcff 100644
--- a/src/vector.h
+++ b/src/vector.h
@@ -1,26 +1,169 @@
+/**
+ * @file vector.h
+ * @brief Dynamic array (vector) implementation.
+ * @details This module provides a generic resizable array data structure
+ *          that can store pointers to any data type. The vector automatically
+ *          grows as elements are added, using a growth factor to amortize
+ *          reallocation costs.
+ */
+
 #ifndef VECTOR_H
 #define VECTOR_H
 
 #include <stddef.h>
 
+/**
+ * @def INITAL_CAPACITY
+ * @brief Initial capacity of a newly created vector.
+ * @details The vector will be allocated with space for this many elements
+ *          when first created. This value is chosen to balance memory usage
+ *          and the number of early reallocations.
+ */
 #define INITAL_CAPACITY 10
+
+/**
+ * @def GROWTH_FACTOR
+ * @brief Multiplicative factor for vector capacity growth.
+ * @details When the vector reaches capacity and needs to grow, the new
+ *          capacity is calculated as (current_capacity * GROWTH_FACTOR).
+ *          A factor of 2 provides good amortized performance.
+ */
 #define GROWTH_FACTOR 2
 
+/**
+ * @struct Vector
+ * @brief A dynamic resizable array (vector) of generic pointers.
+ * @details The vector maintains an underlying array that grows dynamically
+ *          as elements are added. It tracks both the number of elements
+ *          currently stored (size) and the total allocated space (capacity).
+ */
 typedef struct Vector Vector;
+
+/**
+ * @struct Vector
+ * @brief A dynamic array container structure.
+ */
 struct Vector {
+    /**
+     * @brief Array of generic data pointers.
+     * @details A dynamically allocated array of (void*) pointers,
+     *          referencing to the actual data. The array has space for
+     *          at least @p capacity elements. The caller is responsible
+     *          for managing the memory that these pointers reference.
+     */
     void **data;
+
+    /**
+     * @brief The number of elements currently stored in the vector.
+     * @details Valid indices range from 0 to (size - 1). This value is
+     *          incremented when elements are added and decremented when
+     *          elements are removed.
+     */
     size_t size;
+
+    /**
+     * @brief The total allocated space (in number of elements).
+     * @details The underlying @p data array has space for this many pointers.
+     *          When size reaches capacity, the vector is reallocated with
+     *          a new capacity of (capacity * GROWTH_FACTOR). Always
+     *          capacity >= size.
+     */
     size_t capacity;
 };
 
+/**
+ * @brief Allocates and initializes an empty vector.
+ *
+ * @return A pointer to the newly created vector, or NULL if memory
+ *         allocation fails.
+ *
+ * @note The caller is responsible for freeing the returned vector
+ *       using vector_delete().
+ */
 Vector *vector_new(void);
+
+/**
+ * @brief Deallocates the given vector.
+ *
+ * @param v Pointer to the vector to delete. If NULL, this function
+ *          does nothing.
+ *
+ * @note This function deallocates only the vector structure, not the
+ *       data it contains. The caller retains ownership of the data.
+ */
 void vector_delete(Vector *v);
+
+/**
+ * @brief Appends an element to the end of the vector.
+ *
+ * @param v Pointer to the vector.
+ * @param element Pointer to the element to append.
+ *
+ * @note The vector does not take ownership of the element, only stores
+ *       a pointer to it.
+ */
 void vector_push(Vector *v, void *element);
+
+/**
+ * @brief Removes and returns the last element from the vector.
+ *
+ * @param v Pointer to the vector.
+ *
+ * @return The data pointer of the removed last element.
+ *
+ * @pre The vector must not be empty.
+ */
 void *vector_pop(Vector *v);
+
+/**
+ * @brief Returns the element at the given index in the vector.
+ *
+ * @param v Pointer to the vector.
+ * @param index The index of the element to retrieve.
+ *
+ * @return The data pointer at the given index.
+ *
+ * @pre The index must be valid (0 <= index < vector_size(v)).
+ */
 void *vector_get(Vector *v, size_t index);
+
+/**
+ * @brief Sets the element at the given index in the vector.
+ *
+ * @param v Pointer to the vector.
+ * @param index The index of the element to set.
+ * @param element Pointer to the new element.
+ *
+ * @pre The index must be valid (0 <= index < vector_size(v)).
+ */
 void vector_set(Vector *v, size_t index, void *element);
+
+/**
+ * @brief Returns the number of elements in the vector.
+ *
+ * @param v Pointer to the vector.
+ *
+ * @return The number of elements currently in the vector.
+ */
 size_t vector_size(Vector *v);
+
+/**
+ * @brief Checks if the vector is empty.
+ *
+ * @param v Pointer to the vector.
+ *
+ * @return Non-zero if the vector is empty, 0 otherwise.
+ */
 int vector_is_empty(Vector *v);
+
+/**
+ * @brief Removes all elements from the vector.
+ *
+ * @param v Pointer to the vector.
+ *
+ * @note This function only clears the vector structure, not the data
+ *       it contained. The caller retains ownership of the data.
+ */
 void vector_clear(Vector *v);
 
 #endif // !VECTOR_H