From 8dba6d4fa95a9da4b82a4b0d733edeac8fb07cb5 Mon Sep 17 00:00:00 2001
From: Isabell Pflug <isabell.pflug@floating-in.space>
Date: Fri, 28 Jul 2023 04:14:46 +0200
Subject: [PATCH] :recycle: Moved doxygen documentation around until it finally
 works for settings and the SameGame class.

---
 DoxygenLayout.xml      |  8 ++++----
 ThinkPink/samegame.hpp | 41 ++++++++++++++++++++++++++---------------
 ThinkPink/settings.hpp |  2 ++
 3 files changed, 32 insertions(+), 19 deletions(-)

diff --git a/DoxygenLayout.xml b/DoxygenLayout.xml
index 996f781..82aaabd 100644
--- a/DoxygenLayout.xml
+++ b/DoxygenLayout.xml
@@ -20,12 +20,12 @@
       <tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
       <tab type="interfacehierarchy" visible="yes" title="" intro=""/>
     </tab>-->
-    <tab type="classes" visible="yes" title="">
-      <tab type="classlist" visible="yes" title="" intro=""/>
+    <tab type="classlist" visible="yes" title="Classes" intro=""/>
+    <!--<tab type="classes" visible="yes" title="">
       <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
       <tab type="hierarchy" visible="yes" title="" intro=""/>
       <tab type="classmembers" visible="yes" title="" intro=""/>
-    </tab>
+    </tab>-->
     <!--
     <tab type="structs" visible="yes" title="">
       <tab type="structlist" visible="yes" title="" intro=""/>
@@ -186,7 +186,7 @@
   <group>
     <briefdescription visible="yes"/>
     <groupgraph visible="$GROUP_GRAPHS"/>
-    <detaileddescription visible="yes" title="Configuration"/>
+    <detaileddescription visible="yes" title=""/>
     <memberdecl>
       <nestedgroups visible="yes" title="Sections"/>
       <dirs visible="yes" title=""/>
diff --git a/ThinkPink/samegame.hpp b/ThinkPink/samegame.hpp
index 666aa99..b1ac082 100644
--- a/ThinkPink/samegame.hpp
+++ b/ThinkPink/samegame.hpp
@@ -41,8 +41,8 @@ public:
      *
      * 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.
+     * \param[in] rows the number of rows.
+     * \param[in] columns the number of columns.
      */
     void initialiseGameMatrix(int rows, int columns);
 
@@ -50,9 +50,9 @@ public:
      * \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.
+     *      -# 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](#Cell functions).
+     * \param[in] rows the number of rows.
+     * \param[in] columns the number of columns.
      */
     SameGame(int rows, int columns);
     /*! \} */
@@ -60,36 +60,47 @@ public:
     /*!
      * \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.
+     * \param[in] row Number of the row of cell to be selected.
+     * \param[in] column Number of the column of the cell to be selected.
      * \{
      */
 
     /*!
      * \brief getCell returns #gameMatrix[#row][#column].
      * \return #QString color at the requested position.
+     * \param[in] row Number of the row of cell to be selected.
+     * \param[in] column Number of the column of the cell to be selected.
      */
     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.
+     * \brief setCell sets the value of #gameMatrix[#row][#column] to that of #color.
+     * \param[in] color new color for the requested position.
+     * \param[in] row Number of the row of cell to be selected.
+     * \param[in] column Number of the column of the cell to be selected.
      */
     void setCell(int row, int column, QString color);
 
     /*!
-     * \brief checkNeighbour
-     * \param connectedSet
-     * \param color
+     * \brief checkNeighbour checks if input coordinates belong to an existing cell,
+     * whether or not that cell has already been visited, and if the color of that cell matches the color that is currently getting searched for.
+     * \param[in,out] connectedSet keeps track of all coordinate pairs of neighbouring cells that have already been selected.
+     * \param[in] row Number of the row of cell to be selected.
+     * \param[in] column Number of the column of the cell to be selected.
+     * \param[in] color the color that we are searching for.
      */
     void checkNeighbour(std::set<std::vector<int>> *connectedSet, QString color, int row, int column);
 
     /*!
-     * \brief getConnected
-     * \param connectedSet
-     * \param color
+     * \brief getConnected gets all cells that are connected to the original input cell that share the same color recursively, making use
+     * of \ref checkNeighbour to verify each new cell that gets examined.
+     * \param[in,out] connectedSet keeps track of all coordinate pairs of neighbouring cells that have already been selected.
+     * \param[in] color the color that we are searching for.
+     * \param[in] row Number of the row of cell to be selected.
+     * \param[in] column Number of the column of the cell to be selected.
      */
     void getConnected(std::set<std::vector<int>> *connectedSet, QString color, int row, int column);
+    /*! \} */
 
     /*!
      * \brief deleteCell changes the color in the selected cell to an invalid value so that it will get taken out of the game.
diff --git a/ThinkPink/settings.hpp b/ThinkPink/settings.hpp
index f4049da..cb90d05 100644
--- a/ThinkPink/settings.hpp
+++ b/ThinkPink/settings.hpp
@@ -37,6 +37,8 @@
  * \defgroup Settings_src C++ Implementation
  * \ingroup Settings
  * \brief Overview of all sources that initialise and declare the `std::unique_ptr<QSettings>` #settings.
+ * \details Initialising the QSettings using a std::unique_ptr enables usage of user configuration at load time. \n
+ * This means that we can have the grid size of \ref SameGame::gameMatrix and color list \ref SameGame::colors as constants.
  */
 
 /*!