Add Doxygen documentation

.github/workflows/doxygen.yml

@@ -0,0 +1,30 @@
+name: deploy-doxygen
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Doxygen
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen graphviz
+
+      - name: Generate Documentation
+        run: doxygen ./Doxyfile
+
+      - name: Deploying to Gh-pages
+        uses: jinxto/doxygen-env-setup@v1
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -45,3 +45,6 @@ CMakeFiles
 *.app
 /cmake-build-debug-coverage/
 /cmake-build-release-coverage/
+
+#doxygen-folders
+doc/

README.md

@@ -8,7 +8,7 @@
 **mcpp** (Minecraft++) is a library built to interface with Minecraft through [Spigot server](https://www.spigotmc.org/) 
 running the [ELCI](https://github.com/rozukke/ELCI) plugin and using C++. It is currently limited to MacOS/Linux or Windows with WSL.
 
-➡ For more details on the broad strokes of **mcpp**, refer to the [wiki](https://github.com/rozukke/mcpp/wiki/Index)!
+➡ For more details on the broad strokes of **mcpp**, refer to the [wiki](https://github.com/rozukke/mcpp/wiki/Index) or to the [documentation](INSERT_YOUR_URL/classes.html)!
 
 ## History
 This library is based on [mcpi](https://github.com/martinohanlon/mcpi), which is a Python library with similar functionality. 

include/mcpp/block.h

@@ -1,7 +1,10 @@
 #pragma once
 
 #include <ostream>
-
+/**
+ * @file
+ * @brief BlockType class
+ */
 namespace mcpp {
 class BlockType {
   public:
@@ -11,18 +14,45 @@ class BlockType {
     constexpr BlockType(int id = 0, int modifier = 0) : id(id), mod(modifier){};
 
     /**
+     * @brief Equality comparison operator.
+     *
      * Watch out as this also compares the BlockType.mod element of the block,
      * so some equalities may behave in unexpected ways e.g. rotated stairs
+     *
+     * @param other The BlockType to compare with the current instance.
+     *
+     * @return True if the two BlockType instances are not equal, false
+     * otherwise.
      */
     bool operator==(const BlockType& other) const;
 
+    /**
+     * @brief Inequality comparison operator.
+     *
+     * Watch out as this also compares the BlockType.mod element of the block,
+     * so some equalities may behave in unexpected ways e.g. rotated stairs
+     *
+     * @param other The BlockType to compare with the current instance.
+     * @return True if the two BlockType instances are not equal, false
+     * otherwise.
+     */
     bool operator!=(const BlockType& other) const;
 
+    /**
+     * @brief Stream insertion operator for outputting the BlockType to an
+     * output stream.
+     *
+     * @param out The output stream to write to.
+     * @param block The BlockType instance to output.
+     * @return A reference to the output stream after the block information has
+     * been inserted.
+     */
     friend std::ostream& operator<<(std::ostream& out, const BlockType& block);
 
     /**
      * Returns a new BlockType with the same id and specified modifier, useful
      * for rotations etc.
+     *
      * @param modifier New modifier for the BlockType
      * @return New BlockType object with the specified modifier
      */
@@ -32,6 +62,7 @@ class BlockType {
 // Using script to extract ids from https://minecraft-ids.grahamedgecombe.com/
 
 /**
+ * @struct Blocks
  * Struct of static block objects that allows for a "search" of sorts, callable
  * using Blocks::TYPE after importing <block.h>
  */

include/mcpp/connection.h

@@ -4,7 +4,10 @@
 #include <string>
 
 #define FAIL_RESPONSE "Fail"
-
+/** @file
+ * @brief SocketConnection class.
+ *
+ */
 namespace mcpp {
 class SocketConnection {
   private:
@@ -22,6 +25,7 @@ class SocketConnection {
      * Takes in parameters supporting std::stringstream conversion and a string
      * prefix and transforms them into format "prefix(arg1,arg2,arg3)\n" (e.g.
      * "chat.post(test)\n") and sends command to the server.
+     *
      * @tparam Types
      * @param prefix
      * @param args
@@ -44,6 +48,7 @@ class SocketConnection {
 
     /**
      * Sends via sendCommand() and returns the result from endpoint
+     *
      * @tparam T
      * @tparam Types
      * @param prefix

include/mcpp/mcpp.h

@@ -6,23 +6,40 @@
 #include <memory>
 #include <string_view>
 #include <vector>
-
+/** @file
+ * @brief MinecraftConnection class.
+ *
+ */
+
+/**
+ * @brief Namespace containing all the the mcpp library classes.
+ *
+ * The mcpp namespace includes classes and functions designed to facilitate
+ * interaction with the Minecraft world through various server commands
+ * and data manipulations.
+ */
 namespace mcpp {
 class MinecraftConnection {
   private:
-    std::unique_ptr<SocketConnection> conn;
+    std::unique_ptr<SocketConnection>
+        conn; ///< Handle to the socket connection.
 
     static std::vector<std::vector<std::vector<BlockType>>>
-    unflattenBlocksArray(const Coordinate& loc1, const Coordinate& loc2,
-                         const std::vector<BlockType>& inVector);
+    unflattenBlocksArray(
+        const Coordinate& loc1, const Coordinate& loc2,
+        const std::vector<BlockType>&
+            inVector); ///< Helper function to convert flat block array to 3D.
 
-    static std::vector<std::vector<int>>
-    unflattenHeightsArray(const Coordinate& loc1, const Coordinate& loc2,
-                          const std::vector<int>& inVector);
+    static std::vector<std::vector<int>> unflattenHeightsArray(
+        const Coordinate& loc1, const Coordinate& loc2,
+        const std::vector<int>&
+            inVector); ///< Helper function to convert flat height array to 2D.
 
   public:
     /**
-     * Represents the main endpoint for interaction with the minecraft world.
+     * @brief Represents the main endpoint for interaction with the minecraft
+     * world.
+     *
      * @param address String address in IPV4 format, defaults to "localhost"
      * @param port Integer port to run on, defaults to 4711 as that is the port
      * for ELCI
@@ -31,55 +48,66 @@ class MinecraftConnection {
                                  int port = 4711);
 
     /**
-     * Sends a message to the in-game chat, does not require a joined player
+     * @brief Sends a message to the in-game chat, does not require a joined
+     * player
+     *
      * @param message
      */
     void postToChat(const std::string& message);
 
     /**
-     * Performs an in-game minecraft command. Players have to exist on the
-     * server and should be server operators (default with ELCI)
+     * @brief Performs an in-game minecraft command. Players have to exist on
+     * the server and should be server operators (default with ELCI)
+     *
      * @param command Command string in the in-game format (e.g. "time set day")
      */
     void doCommand(const std::string& command);
 
     /**
-     * Sets player pos (block pos of lower half of playermodel) to specified
-     * Coordinate
+     * @brief Sets player pos (block pos of lower half of playermodel) to
+     * specified Coordinate
+     *
      * @param pos Coordinate to set
      */
     void setPlayerPosition(const Coordinate& pos);
 
     /**
-     * Returns a coordinate representing player position (block pos of lower
-     * half of playermodel)
+     * @brief Returns a coordinate representing player position (block pos of
+     * lower half of playermodel)
+     *
      * @return Coordinate of location
      */
     Coordinate getPlayerPosition();
 
     /**
-     * Sets player position to be one above specified tile (i.e. tile = block
-     * player is standing on)
+     * @brief Sets player position to be one above specified tile (i.e. tile =
+     * block player is standing on)
+     *
      * @param tile Coordinate to set
      */
     void setPlayerTilePosition(const Coordinate& tile);
 
     /**
-     * Returns the coordinate location of the block the player is standing on
+     * @brief Returns the coordinate location of the block the player is
+     * standing on
+     *
      * @return Coordinate of location
      */
     Coordinate getPlayerTilePosition();
 
     /**
-     * Sets block at Coordinate loc to the BlockType specified by blockType
+     * @brief Sets block at Coordinate loc to the BlockType specified by
+     * blockType
+     *
      * @param loc
      * @param blockType
      */
     void setBlock(const Coordinate& loc, const BlockType& blockType);
 
     /**
-     * Sets a cuboid of blocks to the specified BlockType blockType, with the
-     * corners of the cuboid provided by the Coordinate loc1 and loc2
+     * @brief Sets a cuboid of blocks to the specified BlockType blockType, with
+     * the corners of the cuboid provided by the Coordinate loc1 and loc2
+     *
      * @param loc1
      * @param loc2
      * @param blockType
@@ -88,15 +116,18 @@ class MinecraftConnection {
                    const BlockType& blockType);
 
     /**
-     * Returns BlockType object from the specified Coordinate loc with modifier
+     * @brief Returns BlockType object from the specified Coordinate loc with
+     * modifier
+     *
      * @param loc
      * @return BlockType of the requested block
      */
     BlockType getBlock(const Coordinate& loc);
 
     /**
-     * Returns a 3D vector of the BlockTypes of the requested cuboid with
+     * @brief Returns a 3D vector of the BlockTypes of the requested cuboid with
      * modifiers
+     *
      * @param loc1 1st corner of the cuboid
      * @param loc2 2nd corner of the cuboid
      * @return 3D vector of BlockType in the specified cuboid.
@@ -105,8 +136,12 @@ class MinecraftConnection {
     getBlocks(const Coordinate& loc1, const Coordinate& loc2);
 
     /**
-     * IMPORTANT: DO NOT USE FOR LARGE AREAS, IT WILL BE VERY SLOW
+     * @brief Returns the height of the specific provided x and y coordinate
+     *
+     * ***IMPORTANT:***
+     * DO NOT USE FOR LARGE AREAS, IT WILL BE VERY SLOW
      * USE getHeights() INSTEAD
+     *
      * Gets the y-value of the highest non-air block at the specified (x, z)
      * coordinate.
      * @param x
@@ -116,8 +151,11 @@ class MinecraftConnection {
     int getHeight(int x, int z);
 
     /**
-     * Provides a scaled option of the getHeight call to allow for considerable
-     * performance gains. USE THIS instead of getHeight in a for loop.
+     * @brief Provides a scaled option of the getHeight call to allow for
+     * considerable performance gains.
+     *
+     * \par USE THIS instead of getHeight in a for loop.
+     *
      * @param loc1
      * @param loc2
      * @return Returns a vector of integers representing the 2D area of heights.