Documented Cell and Terrain classes

src/game/cell.hpp

@@ -47,11 +47,15 @@ public:
     static constexpr WallMask WALL_MASK_FULL  = 0b1111;
 
 public:
+
+    // Create a cell based on the character that represents it
     [[nodiscard]] static Cell from_char(char chr);
 
     Cell() = default;
 
     void set_pos(const Vector2I& in_pos);
+
+    // Set the cell to be of a certain type, with extra relevant information
     void set_item(EItemType in_item_type);
     void set_wall(WallMask in_wall_mask, WallMask in_wall_mask_neg = -1);
     void set_gum(bool big);
@@ -61,10 +65,14 @@ public:
     [[nodiscard]] EItemType get_item() const;
     void                    update_type(const ECellType new_type);
 
+    // Update the cell's sprite handle based on its nature
+    // from the provided data structures
     void update_sprite_handle(
         const std::unordered_map<ECellType, SpriteHandle>& cell_sprite_handles,
         const std::unordered_map<EItemType, SpriteHandle>& item_sprite_handles,
         const std::array<SpriteHandle, 16>&                wall_sprite_handles);
+
+    // Draw the cell to the default or provided surface
     void draw(int32_t terrain_unit_scale, SDL_Surface* surface_override = nullptr) const;
 
 private:

src/game/terrain.hpp

@@ -8,6 +8,14 @@ struct SDL_Surface;
 
 namespace pm
 {
+/*
+ * Representation of the level being played.
+ *
+ * This is the central place of authority for the state of the map,
+ * including collectables: both pellet types, and items a.k.a "fruits".
+ * It handles every interaction with it, including checking for tunnels.
+ */
+
 class Terrain
 {
 public:
@@ -18,6 +26,7 @@ public:
 
     [[nodiscard]] Cell& get_cell(const Vector2I& pos);
 
+    // Get the pixel length of one cell
     [[nodiscard]] int32_t get_unit_length() const
     {
         return unit_length;
@@ -29,6 +38,7 @@ public:
     void tick(double delta_time);
     void draw();
 
+    // Determine if a cell is free to pass through and queryable
     [[nodiscard]] bool is_free(const Vector2I& pos, bool is_door_free = false) const
     {
         if (pos.x() < 0 || pos.y() < 0 || static_cast<uint32_t>(pos.x()) >= width || static_cast<uint32_t>(pos.y()) >= height)
@@ -38,11 +48,15 @@ public:
         return cell_type != ECellType::Wall && (is_door_free || cell_type != ECellType::Door);
     }
 
+    // Determine if a cell is a tunnel (no such cell stored, but accessible)
     [[nodiscard]] bool is_tunnel(const Vector2I& pos) const
     {
+        // Two cells on either horizontal side of the terrain are considered accessible
+        // to allow entities to be teleported to the other side of the level
         return (static_cast<uint32_t>(pos.x() + 2) + width) % (width + 2) >= width;
     }
 
+    // Attempt to eat a collectable that might be at these coordinates
     void eat(const Vector2I& pos);
 
     [[nodiscard]] uint32_t get_width() const { return width; }
@@ -50,8 +64,10 @@ public:
 
     [[nodiscard]] Vector2I closest_free_point(const Vector2I& location) const;
 
+    // Set the color of all walls by setting the wall cache tint
     void set_wall_color(const Uint8 r, const Uint8 g, const Uint8 b) const;
 
+    // Recover the terrain to the state it was in after being loaded
     void reset();
 
 private: