Add documentation and tidy up

Rename clusterFinder to dotClusterFinder

demo/include/demo/change_dot_cluster_behavior.hpp

@@ -9,15 +9,16 @@
 namespace demo {
 
 /**
- * @brief The ChangeDotClusterBehavior makes pacman move towards another cluster of duts.
+ * @brief The ChangeDotClusterBehavior makes pacman move towards the closest dot cluster
+ * that he is not currently inside of.
  */
 class ChangeDotClusterBehavior : public arbitration_graphs::Behavior<Command> {
 public:
     using Ptr = std::shared_ptr<ChangeDotClusterBehavior>;
     using ConstPtr = std::shared_ptr<const ChangeDotClusterBehavior>;
 
     using Cluster = utils::Cluster;
-    using Clusters = utils::ClusterFinder::Clusters;
+    using Clusters = utils::DotClusterFinder::Clusters;
 
     explicit ChangeDotClusterBehavior(EnvironmentModel::Ptr environmentModel,
                                       const std::string& name = "ChangeDotClusterBehavior")

demo/include/demo/environment_model.hpp

@@ -21,7 +21,7 @@ namespace demo {
 class EnvironmentModel {
 public:
     using Cluster = utils::Cluster;
-    using Clusters = utils::ClusterFinder::Clusters;
+    using Clusters = utils::DotClusterFinder::Clusters;
     using Entities = utils::Entities;
     using Maze = utils::Maze;
     using Ghost = utils::Ghost;
@@ -46,7 +46,7 @@ class EnvironmentModel {
     void update(const Game& game) {
         maze_ = std::make_shared<Maze>(game.maze);
         astar_.updateMaze(maze_);
-        clusterFinder_ = utils::ClusterFinder{maze_};
+        clusterFinder_ = utils::DotClusterFinder{maze_};
         updateEntities(game.reg);
     }
 
@@ -80,7 +80,7 @@ class EnvironmentModel {
      * walls nor empty space.
      */
     Clusters dotCluster() const {
-        return clusterFinder_.dotClusters();
+        return clusterFinder_.clusters();
     }
 
     /**
@@ -116,7 +116,7 @@ class EnvironmentModel {
     Maze::ConstPtr maze_;
 
     utils::AStar astar_;
-    utils::ClusterFinder clusterFinder_;
+    utils::DotClusterFinder clusterFinder_;
     mutable util_caching::Cache<Time, GhostWithDistance> closestGhostCache_;
     mutable util_caching::Cache<Time, GhostWithDistance> closestScaredGhostCache_;
 };

demo/include/utils/cluster.hpp

@@ -18,33 +18,39 @@ struct ClusterCell : public BaseCell {
     bool visited{false};
 };
 
+/**
+ * @brief A cluster is defined by a set of points that can be connected by a path which passes through neither walls nor
+ * empty space.
+ */
 struct Cluster {
-    explicit Cluster(const int& clusterId, const std::vector<Position>& dots)
-            : id(clusterId), dots(dots), center{findClusterCenter()} {
+    explicit Cluster(const int& clusterId, const std::vector<Position>& points)
+            : id(clusterId), dots(points), center{findClusterCenter()} {
     }
     bool isInCluster(const Position& target) const {
         return std::any_of(dots.begin(), dots.end(), [target](Position dot) { return dot == target; });
     }
 
     int id;
-    std::vector<Position> dots;
+    Positions dots;
 
-    /// @brief The dot closest to the average position of all the dots of this cluster
-    Position center;
+    Position center; ///< The dot closest to the average position of all the dots of this cluster
 
 private:
     Position findClusterCenter() const;
 };
 
-class ClusterFinder {
+/**
+ * @brief Search and store all clusters of dots (including power pellets) given the maze state.
+ */
+class DotClusterFinder {
 public:
+    using Cell = ClusterCell;
     using Clusters = std::vector<Cluster>;
     using ClusterMazeAdapter = MazeAdapter<ClusterCell>;
-    using Cell = ClusterCell;
 
-    explicit ClusterFinder(Maze::ConstPtr maze) : maze_(std::move(maze)), clusters_{findDotClusters()} {
+    explicit DotClusterFinder(Maze::ConstPtr maze) : maze_(std::move(maze)), clusters_{findDotClusters()} {
     }
-    Clusters dotClusters() const {
+    Clusters clusters() const {
         return clusters_;
     }
 

demo/include/utils/maze.hpp

@@ -97,7 +97,13 @@ struct BaseCell {
     TileType type;
 };
 
-template <typename CellType>
+/**
+ * @brief Adapter class for storing properties per cell of the underlying maze.
+ *
+ * The MazeAdapter is a helpful little class to put between an algorithm and the actual maze class. It can be used to
+ * store properties per cell of the maze grid using the templated CellType class. Cells are lazily initialized.
+ */
+template <typename CellType = BaseCell>
 class MazeAdapter {
 public:
     using MazeStateConstPtr = std::shared_ptr<const MazeState>;

demo/src/cluster.cpp

@@ -9,9 +9,9 @@ Position Cluster::findClusterCenter() const {
     int sumX = 0;
     int sumY = 0;
 
-    for (const auto& dot : dots) {
-        sumX += dot.x;
-        sumY += dot.y;
+    for (const auto& point : dots) {
+        sumX += point.x;
+        sumY += point.y;
     }
 
     int avgX = std::floor(sumX / dots.size());
@@ -32,7 +32,7 @@ Position Cluster::findClusterCenter() const {
     return closestDot;
 }
 
-ClusterFinder::Clusters ClusterFinder::findDotClusters() const {
+DotClusterFinder::Clusters DotClusterFinder::findDotClusters() const {
     ClusterMazeAdapter mazeAdapter(maze_);
     Clusters clusters;
     int clusterId = 0;
@@ -52,7 +52,7 @@ ClusterFinder::Clusters ClusterFinder::findDotClusters() const {
     return clusters;
 }
 
-Positions ClusterFinder::expandDot(const Cell& start, const ClusterMazeAdapter& mazeAdapter) const {
+Positions DotClusterFinder::expandDot(const Cell& start, const ClusterMazeAdapter& mazeAdapter) const {
     Positions dots;
 
     std::queue<Position> bfsQueue;

demo/test/cluster.cpp

@@ -24,9 +24,9 @@ TEST_F(ClusterTest, dotClusters) {
                         "#####"};
     environmentModel_->setMaze({5, 5}, str);
 
-    ClusterFinder clusterFinder(environmentModel_->maze());
+    DotClusterFinder dotClusterFinder(environmentModel_->maze());
 
-    std::vector<Cluster> clusters = clusterFinder.dotClusters();
+    std::vector<Cluster> clusters = dotClusterFinder.clusters();
 
     ASSERT_EQ(clusters.size(), 2);
     EXPECT_EQ(clusters.front().dots.size(), 3);

demo/test/mock_environment_model.hpp

@@ -67,7 +67,7 @@ class MockEnvironmentModel : public EnvironmentModel {
     void setMaze(const Position& size, const char (&str)[Size]) {
         maze_ = std::make_shared<Maze>(makeCustomMazeState({size.x, size.y}, str));
         astar_ = utils::AStar(maze_);
-        clusterFinder_ = utils::ClusterFinder(maze_);
+        clusterFinder_ = utils::DotClusterFinder(maze_);
     }
     void setEmptyMaze() {
         const char str[] = {"##########"