From 8b79e4f9cd995ec0c0e4a7c57d2319cf0045229c Mon Sep 17 00:00:00 2001 From: ItsDrike Date: Mon, 24 Mar 2025 19:08:48 +0100 Subject: [PATCH] Add doxygen comments --- src/ball.cpp | 17 ++++++++++++++++- src/ball.h | 24 ++++++++++++++++++++++++ src/mainwindow.cpp | 3 +++ src/mainwindow.h | 25 +++++++++++++++++++++++++ src/platform.cpp | 5 +++++ src/platform.h | 26 ++++++++++++++++++++++++++ 6 files changed, 99 insertions(+), 1 deletion(-) diff --git a/src/ball.cpp b/src/ball.cpp index 3f27416..3149eb4 100644 --- a/src/ball.cpp +++ b/src/ball.cpp @@ -5,18 +5,33 @@ #include #include +/// 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) : m_parent{parent}, m_platform{platform}, m_isSpawning{true} { diff --git a/src/ball.h b/src/ball.h index fafcb41..6c0397f 100644 --- a/src/ball.h +++ b/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); + /** + * @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: diff --git a/src/mainwindow.cpp b/src/mainwindow.cpp index 501c9b2..8f08960 100644 --- a/src/mainwindow.cpp +++ b/src/mainwindow.cpp @@ -4,8 +4,11 @@ #include #include +/// 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) : diff --git a/src/mainwindow.h b/src/mainwindow.h index 584c10c..a21b961 100644 --- a/src/mainwindow.h +++ b/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; diff --git a/src/platform.cpp b/src/platform.cpp index cb2eb50..74af44c 100644 --- a/src/platform.cpp +++ b/src/platform.cpp @@ -3,10 +3,15 @@ #include #include +/// 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} { diff --git a/src/platform.h b/src/platform.h index 629e1cf..f85be2d 100644 --- a/src/platform.h +++ b/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: