docs: more comments

COMPILE.txt

@@ -1,2 +1 @@
-mkdir build
+g++ -std=c++23 -Wall ./main.cpp -o ./adventura && ./adventura
-g++ -std=c++23 -Wall ./main.cpp -o ./build/testCompiled && ./build/testCompiled

block.hpp

@@ -11,7 +11,22 @@ private:
     BlockSettings settings;
 
 public:
+    /**
+     * Constructs a block with the given identifier, encoding and settings.
+     *
+     * @param id The (unique) identifier of the block.
+     * @param encoding The encoding of the block, which is the character used to represent it in the game world.
+     * @param settings The settings of the block, which define how the block behaves in the game world.
+     */
     Block(Identifier id, char encoding, BlockSettings settings) : Block(id, encoding, Color::RESET, settings) {};
+    /**
+     * Constructs a block with the given identifier, encoding, color and settings.
+     *
+     * @param id The (unique) identifier of the block.
+     * @param encoding The encoding of the block, which is the character used to represent it in the game world.
+     * @param color The color of the block.
+     * @param settings The settings of the block, which define how the block behaves in the game world.
+     */
     Block(Identifier id, char encoding, Color color, BlockSettings settings) {
         this->id = id;
         this->encoding = encoding;
@@ -19,19 +34,55 @@ public:
         this->settings = settings;
     };
 
+    /**
+     * Returns the settings associated with the block.
+     *
+     * @return The settings of the block, including solidity, pushability, and more.
+     */
     BlockSettings getSettings() {
         return settings;
     }
 
+    /**
+     * Gets the identifier of the block.
+     *
+     * This identifier is used by the game to uniquely identify the block.
+     *
+     * @return The identifier of the block.
+     */
     Identifier getId() {
         return id;
     }
+
+    /**
+     * Returns the color of the block.
+     *
+     * The color is used when drawing the block in the world.
+     *
+     * @return The color of the block.
+     */
     Color getColor() {
         return color;
     }
+    
+    /**
+     * Returns the character encoding of the block.
+     *
+     * This character is used in the text file as well as the terminal to represent the block.
+     *
+     * @return The character encoding of the block.
+     */
     char getEncoding() {
         return encoding;
     }
+    
+    /**
+     * Sets the character encoding for the block.
+     *
+     * This encoding is used to represent the block in text files and the terminal.
+     *
+     * @param encoding The character encoding to set for the block.
+     */
     void setEncoding(char encoding) {
         this->encoding = encoding;
     }

blockPos.hpp

@@ -3,28 +3,67 @@ class BlockPos {
     int x;
     int y;
 public:
+    /**
+     * Define an in-world position.
+     * 
+     * @param x The x-coordinate of the BlockPos.
+     * @param y The y-coordinate of the BlockPos.
+     */
     BlockPos(int x, int y) {
         this->x = x;
         this->y = y;
     }
+    
+    /**
+     * @return The x-coordinate of the BlockPos.
+     */
     int getX() {
         return x;
     }
+
+    /**
+     * @return The y-coordinate of the BlockPos.
+     */
     int getY() {
         return y;
     }
+
+    /**
+     * @return The x-coordinate of the BlockPos as an unsigned integer.
+     * @pre x >= 0
+     */
     unsigned int getUnsignedX() {
         return static_cast<unsigned int>(x);
     }
+
+    /**
+     * @return The y-coordinate of the BlockPos as an unsigned integer.
+     * @pre y >= 0
+     */
     unsigned int getUnsignedY() {
         return static_cast<unsigned int>(y);
     }
+    
+    /**
+     * @return True if the BlockPos is negative, false otherwise.
+     * 
+     * A BlockPos is considered negative if either the x-coordinate or the y-coordinate is negative.
+     */
     bool isNegative() {
         return x < 0 || y < 0;
     }
+
+    /**
+     * Add the given coordinates to the BlockPos.
+     * 
+     * @param x The x-coordinate to add.
+     * @param y The y-coordinate to add.
+     * @return The BlockPos with the given coordinates added.
+     */
     BlockPos add(int x, int y) {
         return BlockPos(this->x + x, this->y + y);
     }
+    
     BlockPos operator+(BlockPos offset) {
         return BlockPos(this->getX() + offset.getX(), this->getY() + offset.getY());
     }

blockRegistry.hpp

@@ -19,6 +19,9 @@ public:
     Block BOX = Block(Identifier("adventura", "box"), 'x', Color::BRIGHT_CYAN, BlockSettingsBuilder().pushable().collidable().gravity().build());
     Block SAND = Block(Identifier("adventura", "sand"), '*', Color::BRIGHT_YELLOW, BlockSettingsBuilder().brittle().gravity().build());
 
+    /**
+     * Constructor for BlockRegistry. Registers all built-in blocks.
+     */
     BlockRegistry() {
         registerBlock(AIR);
         registerBlock(WATER);
@@ -48,9 +51,13 @@ public:
     }
 
 private:
-    Block registerBlock(Block& block) {
+    /**
+     * Registers a block in the registry.
+     * 
+     * @param block The block to register.
+     */
+    void registerBlock(Block& block) {
         registeredBlocks.push_back(block);
-        return block;
     }
     vector<Block> registeredBlocks;
 };

color.hpp

@@ -12,6 +12,7 @@ enum class Color {
     BRIGHT_CYAN= 96,
     BRIGHT_WHITE= 97
 };
+
 std::ostream& operator<<(std::ostream& os, Color color) {
     return os << "\033[" << static_cast<int>(color) << "m";
 }

identifier.hpp

@@ -8,7 +8,17 @@ public:
     std::string nameSpace;
     std::string path;
 
-    Identifier(std::string nameSpace, std::string path) : nameSpace(nameSpace), path(path) {}
+
+    /**
+     * Construct a new Identifier.
+     * Identifiers are used to uniquely identify blocks, regardless of their encoding.
+     * 
+     * @param nameSpace The namespace of the Identifier.
+     * @param path The path of the Identifier.
+     */
+    Identifier(std::string nameSpace, std::string path) : nameSpace(nameSpace), path(path) {
+        
+    }
 
     std::ostream& operator<<(std::ostream& out) {
         out << nameSpace << ":" << path;

player.hpp

@@ -8,21 +8,52 @@
 
 class Player {
 public:
+    /**
+     * Initializes a new Player at the specified starting position in the provided world.
+     *
+     * @param pos The initial position of the player within the world.
+     * @param world A reference to the World object representing the game world.
+     */
     Player(BlockPos pos, World& world) : world(world) {
         this->pos = pos;
         this->world = world;
         playerTexture = REGULAR_PLAYER_TEXTURE;
     }
     
+    /**
+     * Retrieves the current position of the player in the world.
+     *
+     * @return The current BlockPos representing the player's position.
+     */
     BlockPos getPos() {
         return pos;
     }
+
+    /**
+     * Move the player by the specified x and y offsets.
+     *
+     * @param x The x offset to move by.
+     * @param y The y offset to move by.
+     */
     void move(int x, int y) {
         move(BlockPos(x, y));
     }
+
+    /**
+     * Move the player by the specified BlockPos offset.
+     *
+     * @param offset The BlockPos representing the offset to move the player by.
+     */
     void move(BlockPos offset) {
         setPos(pos + offset);
     }
+
+    
+    /**
+     * Updates the player's position and checks for any conditions that would update the state of the player.
+     * 
+     * @param pos The position to move the player to.
+     */
     void setPos(BlockPos pos) {
         if (!world.containsPos(pos)) {
             alive = false;
@@ -50,17 +81,39 @@ public:
 
         if (world.getBlockAt(pos.add(0, 2)).getSettings().isLethal()) unalive();
     }
+
+    /**
+     * Handle the unfortunate case of a player dying :(
+     */
     void unalive() {
         playerTexture = DEAD_PLAYER_TEXTURE;
         redraw(world, this->mapToWorldspace());
         alive = false;
     }
+    
+    /**
+     * Checks if the player is still alive.
+     *
+     * @return true if the player is alive, false otherwise.
+     */
     bool isAlive() {
         return alive;
     }
+    
+    /**
+     * Checks if the player has reached the goal in the current world.
+     *
+     * @return true if the player has reached the goal, false otherwise.
+     */
     bool hasReachedGoal() {
         return reachedGoal;
     }
+    
+    /**
+     * Maps the player texture to the player's position in the current game world.
+     * 
+     * @return A 2D vector of characters representing the player's position in the world.
+     */
     vector<vector<char>> mapToWorldspace() {
         vector<vector<char>> map;
         for (unsigned int y = 0; y <= world.getMaxY(); y++) {

world.hpp

@@ -1,7 +1,7 @@
 #pragma once
 #include <vector>
 #include <array>
-#include "fileutils.hpp"
+#include "fileUtils.hpp"
 #include "block.hpp"
 #include "blockRegistry.hpp"
 #include "blockPos.hpp"