Add doxygen comments

src/ball.cpp

@@ -5,18 +5,33 @@
 #include <qglobal.h>
 #include <random>
 
+/// The radius of the ball.
 #define RADIUS 15
-#define TOP_MARGIN 35 // This is the menu bar height (no easy way to get programatically)
+/// The margin from the top, accounting for the menu bar height.
+#define TOP_MARGIN 35
 
+/// The update interval (milliseconds) for the ball movement.
 #define TICK_SPEED 10
 
+/// Maximum horizontal speed of the ball.
 #define MAX_X_SPEED 5.0
+/// Minimum horizontal speed of the ball.
 #define MIN_X_SPEED 2.0
+/// Maximum vertical speed of the ball.
 #define MAX_Y_SPEED 8.0
+/// Minimum vertical speed of the ball.
 #define MIN_Y_SPEED 4.0
 
+/// Vertical speed increase applied on each tick
 #define GRAVITY 0.022
 
+/**
+ * @brief Generates a random double between minValue and maxValue.
+ *
+ * @param minValue The minimum possible value.
+ * @param maxValue The maximum possible value.
+ * @return A random double within the specified range.
+ */
 double getRandomDouble(double minValue, double maxValue);
 
 Ball::Ball(QWidget* parent, std::shared_ptr<Platform> platform) : m_parent{parent}, m_platform{platform}, m_isSpawning{true} {

src/ball.h

@@ -10,8 +10,23 @@ class Ball : public QTimer {
     Q_OBJECT
 
   public:
+    /**
+    * @brief Constructs a Ball object.
+    *
+    * The ball starts at a random horizontal position and below the screen vertically.
+    * It's speed is also randomized, though guaranteed to go vertically up.
+    * It is initially in the "spawning" state, during which it can't hit a platform.
+    *
+    * @param parent Pointer to the parent widget.
+    * @param platform Shared pointer to the platform object.
+    */
     Ball(QWidget* parent, std::shared_ptr<Platform> platform);
 
+    /**
+    * @brief Draws the ball on the screen.
+    *
+    * @param painter Reference to the QPainter used for rendering.
+    */
     void draw(QPainter& painter);
 
   signals:
@@ -19,6 +34,15 @@ class Ball : public QTimer {
     void caught(Ball* ball);
 
   protected:
+    /**
+    * @brief Handles the ball's movement and collision detection.
+    *
+    * Updates the position of the ball, checks for collisions with walls, the ceiling,
+    * the platform, or falling through the bottom of the screen. Emits appropriate signals
+    * if the ball is caught or falls through.
+    *
+    * @param event Pointer to the timer event (not used explicitly).
+    */
     virtual void timerEvent(QTimerEvent*) override;
 
   private:

src/mainwindow.cpp

@@ -4,8 +4,11 @@
 #include <memory>
 #include <qnamespace.h>
 
+/// Initial spawn speed of the ball in milliseconds.
 #define INIT_SPAWN_SPEED 2000.0
+/// Speed increase per caught ball (ms).
 #define SPAWN_SPEED_INCREASE 50.0
+/// Minimum spawn speed limit (ms).
 #define MIN_SPAWN_SPEED 800.0
 
 MainWindow::MainWindow(QWidget* parent) :

src/mainwindow.h

@@ -25,14 +25,39 @@ class MainWindow : public QMainWindow {
     bool rightArrowPressed;
 
   private slots:
+    /**
+    * @brief Handles the event when a ball falls through the bottom.
+    * @param ball The ball that fell through.
+    */
     void ballFell(Ball* ball);
+
+    /**
+    * @brief Handles the event when a ball is caught by the platform.
+    * @param ball The ball that was caught.
+    */
     void ballCaught(Ball* ball);
+
+    /**
+    * @brief Handles the ball spawn timer event.
+    */
     void onBallSpawn();
 
   protected:
+    /**
+    * @brief Paint event handler to render the game objects.
+    * @param event Paint event.
+    */
     virtual void paintEvent(QPaintEvent*) override;
 
+    /**
+    * @brief Deletes a given ball from the game.
+    * @param ball The ball to be deleted.
+    */
     void deleteBall(Ball* ball);
+
+    /**
+    * @brief Spawns a new ball in the game.
+    */
     void spawnBall();
 
     void keyPressEvent(QKeyEvent* event) override;

src/platform.cpp

@@ -3,10 +3,15 @@
 #include <QDebug>
 #include <qapplication.h>
 
+/// The update interval (milliseconds) for the platform movement.
 #define TICK_SPEED 15
+/// The width of the platform.
 #define PLATFORM_WIDTH 100
+/// The height of the platform.
 #define PLATFORM_HEIGHT 20
+/// The distance of the platform from the bottom of the window.
 #define PLATFORM_MARGIN_BOTTOM 80
+/// The speed at which the platform moves.
 #define SPEED 10.0
 
 Platform::Platform(MainWindow* parent) : m_parent{parent} {

src/platform.h

@@ -14,13 +14,39 @@ class Platform : public QTimer {
     Q_OBJECT
 
   public:
+    /**
+    * @brief Constructs a Platform object.
+    *
+    * Initializes the platform at a random horizontal position within the window
+    * and sets its vertical position near the bottom.
+    *
+    * @param parent Pointer to the main window.
+    */
     Platform(MainWindow* parent);
 
+    /**
+    * @brief Draws the platform on the screen.
+    *
+    * @param painter Reference to the QPainter used for rendering.
+    */
     void draw(QPainter& painter);
 
+    /**
+    * @brief Returns the bounding rectangle of the platform.
+    *
+    * @return QRect representing the platform's current position and size.
+    */
     QRect rect() const;
 
   protected:
+    /**
+    * @brief Handles the platform's movement and updates its position.
+    *
+    * The platform moves left or right depending on the arrow key states.
+    * Ensures the platform does not move beyond window boundaries.
+    *
+    * @param event Pointer to the timer event (not used explicitly).
+    */
     virtual void timerEvent(QTimerEvent*) override;
 
   private: