From 8522dc296f9640a63ba88ffc3dfa41f418df3277 Mon Sep 17 00:00:00 2001
From: Isabell Pflug <isabell.pflug@floating-in.space>
Date: Thu, 27 Jul 2023 20:30:28 +0200
Subject: [PATCH] :memo: Added documentation for SameGame class and its members

---
 ThinkPink/samegame.h | 91 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 90 insertions(+), 1 deletion(-)

diff --git a/ThinkPink/samegame.h b/ThinkPink/samegame.h
index faec1ef..83c8e6f 100644
--- a/ThinkPink/samegame.h
+++ b/ThinkPink/samegame.h
@@ -6,20 +6,109 @@
 #include <QSettings>
 #include <QString>
 
+/**
+ * \brief The SameGame class. Stores the underlying informations of the game grid and its colors. Provides the base game functionality of checking the neighbours of clicked cells.
+ * The update of the grid though gets triggered from the #MainWindow.
+ */
 class SameGame
 {
 private:
+    /*!
+     * \brief the gameMatrix. Stores the colors of the grid inside of nested vectors.
+     * \todo make it all much much much more efficient by using std::size_t indices instead of [QStrings](#QString).
+     *      -# Why do I have a list of colors if I am spamming the RAM with color name strings?
+     *      -# this includes having to add the #QString used for the nonvalid color for each cell removed to the #colors list.
+     */
     std::vector<std::vector<QString>> gameMatrix;
+
+    /*!
+     * \brief Stores all the defined colors from the #settings unique pointer as [QStrings](#QString).
+     */
     const QStringList colors;
+
 public:
+
+    /*!
+     * \name Initialisation
+     * \brief Functions that set-up the #gameMatrix.
+     * \{
+    */
+
+    /*!
+     * \brief Initialises the game matrix.
+     *
+     * This function takes the number of rows and columns as arguments and creates a game grid of the respective size that it stores into #gameMatrix with randomly picked colors for each cell from #colors .
+     *
+     * \param rows the number of rows.
+     * \param columns the number of columns.
+     */
     void initialiseGameMatrix(int rows, int columns);
+
+    /*!
+     * \brief Constructor for the SameGame class. Takes the colors from #settings and stores them into #colors.
+     * \todo Why did I not make the amount of rows and columns constants read from #settings as well, like the #QStringList #colors?
+     *      -# it is included in the #settings pointer anyways. no reason to have it being a variable.
+     *      -# because of that, I am not going to group the rows and columns parameters of the constructor and the #initialiseGameMatrix() function like I did for the [selection parameters](#SelectionParameters).
+     * \param rows the number of rows.
+     * \param columns the number of columns.
+     */
     SameGame(int rows, int columns);
+    /*! \} */
+
+    /*!
+     * \name Cell functions
+     * \brief Functions that all use coordinates of a specific cell from the #gameMatrix as parameters.
+     * \param row Number of the row of cell to be selected.
+     * \param column Number of the column of the cell to be selected.
+     * \{
+     */
+
+    /*!
+     * \brief getCell returns #gameMatrix[#row][#column].
+     * \return #QString color at the requested position.
+     */
     QString getCell(int row, int column);
+
+    /*!
+     * \brief setCell sets the value of #gameMatrix[#row][#column] to #color.
+     * \param color new color for the requested position.
+     */
     void setCell(int row, int column, QString color);
+
+    /*!
+     * \brief checkNeighbour
+     * \param connectedSet
+     * \param color
+     */
     void checkNeighbour(std::set<std::vector<int>> *connectedSet, QString color, int row, int column);
+
+    /*!
+     * \brief getConnected
+     * \param connectedSet
+     * \param color
+     */
     void getConnected(std::set<std::vector<int>> *connectedSet, QString color, int row, int column);
-    int getNumberOfColors();
+
+    /*!
+     * \brief deleteCell changes the color in the selected cell to an invalid value so that it will get taken out of the game.
+     */
     void deleteCell(int row, int column);
+    /*! \} */
+
+    /*!
+     * \name Information functions
+     * \brief Functions that provide information about the status of the #SameGame.
+     * \{
+     */
+
+    /*!
+     * \brief getNumberOfColors returns number of unique colors.
+     * \todo check relevancy! Might be unneccessary due to colors being stored in #settings
+     * \return number of unique colors.
+     */
+    int getNumberOfColors();
+    /*! \} */
+
 };
 
 #endif // SAMEGAME_H