docs: restore Doxygen comments and add inline documentation

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Author: YJack0000

include/core/Environment.hpp

@@ -10,45 +10,122 @@
 #include "Organism.hpp"
 #include "index/ISpatialIndex.hpp"
 
+/**
+ * @brief The 2D simulation world that owns all objects and drives the tick loop.
+ *
+ * Environment manages a spatial index for efficient proximity queries and an
+ * object map keyed by UUID. Each simulation tick runs three phases in order:
+ *  1. **Interactions** -- close-range actions (eating, fighting) within size radius.
+ *  2. **Reactions** -- movement decisions based on objects within reaction radius.
+ *  3. **Post-iteration** -- life-span deduction, movement, and spatial-index sync.
+ *
+ * After the requested iterations complete, a cleanup pass removes dead organisms
+ * and consumed food from the world.
+ *
+ * Both handleInteractions() and handleReactions() run single-threaded so that
+ * Python strategy callbacks can safely acquire the GIL without deadlocks.
+ */
 class Environment {
 public:
+    /**
+     * @brief Construct an environment with the given dimensions.
+     * @param width  Horizontal extent of the world (x in [0, width]).
+     * @param height Vertical extent of the world (y in [0, height]).
+     * @param type   Spatial-index implementation: "default" (brute-force) or "optimized" (quadtree).
+     * @param numThreads Reserved for future multi-threaded support (currently unused).
+     */
     Environment(int width, int height, std::string type = "default", int numThreads = 1);
+
+    /** @brief Horizontal extent of the simulation area. */
     int getWidth() const { return width; }
+    /** @brief Vertical extent of the simulation area. */
     int getHeight() const { return height; }
 
+    /**
+     * @brief Place an organism into the environment at the given coordinates.
+     * @param organism Shared pointer to the organism.
+     * @param x X-coordinate (must be within bounds).
+     * @param y Y-coordinate (must be within bounds).
+     * @throws std::out_of_range If (x, y) is outside the environment bounds.
+     */
     void add(const std::shared_ptr<Organism>& organism, float x, float y);
+
+    /**
+     * @brief Place a food item into the environment at the given coordinates.
+     * @param food Shared pointer to the food.
+     * @param x X-coordinate (must be within bounds).
+     * @param y Y-coordinate (must be within bounds).
+     * @throws std::out_of_range If (x, y) is outside the environment bounds.
+     */
     void add(const std::shared_ptr<Food>& food, float x, float y);
 
+    /**
+     * @brief Remove an organism from the environment and spatial index.
+     * @param organism The organism to remove.
+     * @throws std::runtime_error If the organism is not found.
+     */
     void remove(const std::shared_ptr<Organism>& organism);
+
+    /**
+     * @brief Remove a food item from the environment and spatial index.
+     * @param food The food to remove.
+     * @throws std::runtime_error If the food is not found.
+     */
     void remove(const std::shared_ptr<Food>& food);
 
+    /** @brief Remove all objects and reset statistics (dead organisms, food consumption). */
     void reset();
 
-    void simulateIteration(int,
+    /**
+     * @brief Run the simulation for a number of iterations.
+     * @param iterations Number of ticks to simulate; stops early if the world is empty.
+     * @param on_each_iteration Optional callback invoked after every tick (useful for rendering).
+     */
+    void simulateIteration(int iterations,
                            std::function<void(const Environment&)> on_each_iteration = nullptr);
 
+    /** @brief Snapshot of all living organisms currently in the environment. */
     std::vector<std::shared_ptr<Organism>> getAllOrganisms() const;
+    /** @brief Snapshot of all remaining (uneaten) food items. */
     std::vector<std::shared_ptr<Food>> getAllFoods() const;
+    /** @brief Snapshot of every environment object (organisms + food). */
     std::vector<std::shared_ptr<EnvironmentObject>> getAllObjects() const;
+    /** @brief Organisms that have died during the simulation (accumulated across ticks). */
     std::vector<std::shared_ptr<Organism>> getDeadOrganisms() const;
+    /** @brief Total number of food items consumed since the last reset(). */
     unsigned long getFoodConsumptionInIteration() const;
 
 private:
     int width, height;
-    std::string type;
+    std::string type;  ///< Spatial-index variant identifier ("default" or "optimized").
     std::unique_ptr<ISpatialIndex<boost::uuids::uuid>> spatialIndex;
+    /// Maps object UUID -> shared_ptr; serves as the authoritative object store.
     std::unordered_map<boost::uuids::uuid, std::shared_ptr<EnvironmentObject>> objectsMapper;
 
-    std::vector<std::shared_ptr<Organism>> deadOrganisms;
-    unsigned long foodConsumption = 0;
+    std::vector<std::shared_ptr<Organism>> deadOrganisms;  ///< Accumulated dead organisms.
+    unsigned long foodConsumption = 0;                      ///< Eaten-food counter.
 
-    int numThreads = 1;
+    int numThreads = 1;  ///< Reserved for future multi-threaded tick processing.
 
+    /**
+     * @brief Validate that coordinates lie within the environment bounds.
+     * @throws std::out_of_range If out of bounds.
+     */
     void checkBounds(float x, float y) const;
+
+    /** @brief Synchronise organism positions with the spatial index after movement. */
     void updatePositionsInSpatialIndex();
+
+    /** @brief Run close-range interaction phase for all living organisms. */
     void handleInteractions();
+
+    /** @brief Run reaction (movement-decision) phase for all living organisms. */
     void handleReactions();
+
+    /** @brief Invoke postIteration() on every object and sync positions. */
     void postIteration();
+
+    /** @brief Remove dead organisms and eaten food from the world. */
     void cleanUp();
 };
 

include/core/EnvironmentObject.hpp

@@ -4,24 +4,48 @@
 #include <boost/uuid/uuid.hpp>
 #include <boost/uuid/uuid_generators.hpp>
 
+/**
+ * @brief Base class for all objects that can exist within the simulation environment.
+ *
+ * Every environment object has a unique UUID and a 2D position. Subclasses include
+ * Organism and Food. The UUID is used as the key in the spatial index and object map.
+ */
 class EnvironmentObject {
 public:
+    /**
+     * @brief Construct an environment object at the given coordinates.
+     * @param x Initial x-coordinate.
+     * @param y Initial y-coordinate.
+     */
     EnvironmentObject(float x, float y)
         : id(boost::uuids::random_generator()()), position(std::make_pair(x, y)) {}
 
+    /** @brief Return the unique identifier for this object. */
     boost::uuids::uuid getId() const { return id; }
 
     virtual ~EnvironmentObject() = default;
+
+    /**
+     * @brief Called once per simulation tick after interactions and reactions.
+     *
+     * Subclasses override this to perform per-tick bookkeeping (e.g. life-span
+     * deduction, movement).
+     */
     virtual void postIteration() {};
 
-    // [TODO] change this - very bad implementation in order to make organism
-    // move
+    /** @brief Get the current (x, y) position. */
     virtual std::pair<float, float> getPosition() const { return position; }
+
+    /**
+     * @brief Set the position to new coordinates.
+     * @param x New x-coordinate.
+     * @param y New y-coordinate.
+     */
     virtual void setPosition(float x, float y) { position = std::make_pair(x, y); }
 
 private:
-    boost::uuids::uuid id;
-    std::pair<float, float> position;
+    boost::uuids::uuid id;               ///< Unique identifier for spatial-index lookups.
+    std::pair<float, float> position;     ///< Current (x, y) position in the environment.
 };
 
 #endif

include/core/Food.hpp

@@ -3,17 +3,31 @@
 
 #include "EnvironmentObject.hpp"
 
+/** @brief Lifecycle state of a Food item. */
 enum class FoodState { FRESH, EATEN };
 
+/**
+ * @brief A consumable food item placed in the environment.
+ *
+ * Food starts in the FRESH state and transitions to EATEN once an organism
+ * consumes it. Eaten food is removed during the environment's cleanup phase.
+ */
 class Food : public EnvironmentObject {
 public:
+    /** @brief Construct a fresh food item at origin (0,0). Position is set later via setPosition(). */
     Food() : EnvironmentObject(0, 0) {}
+
+    /** @brief Check whether this food is still available for consumption. */
     bool canBeEaten() { return state == FoodState::FRESH; }
+
+    /** @brief Mark this food as consumed. Subsequent canBeEaten() calls return false. */
     void eaten() { state = FoodState::EATEN; }
+
+    /** @brief Energy value awarded to the organism that eats this food. */
     int getEnergy() const { return 500; }
 
 private:
-    FoodState state = FoodState::FRESH;
+    FoodState state = FoodState::FRESH;  ///< Tracks whether the food has been consumed.
 };
 
 #endif

include/core/Genes.hpp

@@ -3,19 +3,49 @@
 
 #include <functional>
 
+/**
+ * @brief Encapsulates a 4-byte DNA sequence and its mutation logic.
+ *
+ * Each byte in the DNA array encodes a different organism trait (speed, size,
+ * awareness, and a reserved gene). Mutation can be customised by injecting a
+ * MutationFunction, which is also propagated to offspring during reproduction.
+ */
 class Genes {
 public:
+    /** @brief Callable that mutates a 4-byte DNA array in place. */
     using MutationFunction = std::function<void(char[4])>;
 
+    /**
+     * @brief Construct genes from a raw DNA string using the default mutation logic.
+     * @param dnaStr Pointer to at least 4 bytes representing the gene values.
+     */
     Genes(const char *dnaStr);
+
+    /**
+     * @brief Construct genes with a custom mutation function.
+     * @param dnaStr Pointer to at least 4 bytes representing the gene values.
+     * @param customMutationLogic Callable applied during mutate(); nullptr uses the default.
+     */
     Genes(const char *dnaStr, MutationFunction customMutationLogic);
 
+    /** @brief Apply the mutation function to the DNA array. */
     void mutate();
+
+    /**
+     * @brief Retrieve a single gene value.
+     * @param index Gene index (0 = speed, 1 = size, 2 = awareness, 3 = reserved).
+     * @return The raw gene byte value.
+     */
     char getDNA(int index) const;
 
 private:
-    char dna[4];
-    MutationFunction mutationLogic;
+    char dna[4];                     ///< Raw gene data; each byte maps to one trait.
+    MutationFunction mutationLogic;  ///< Mutation strategy applied during mutate().
+
+    /**
+     * @brief Built-in mutation that adds a small random delta ([-3, 3]) to each gene.
+     * @param dna The 4-byte DNA array to mutate in place.
+     */
     static void defaultMutationLogic(char dna[4]);
 };