feat: Document entire repository

README.md

@@ -31,6 +31,24 @@ Contact us in our [Discord Server](https://discord.gg/WJ9XF9czVT)!
 For more information on each function supported by Bruce, [read our wiki here](https://github.com/pr3y/Bruce/wiki).
 Also, [read our FAQ](https://github.com/pr3y/Bruce/wiki/FAQ)
 
+## :file_folder: Documentation
+
+This repository is fully documented using Doxygen. To generate the documentation, run the following command:
+
+```sh
+doxygen Doxyfile
+```
+
+The documentation will be generated in the `docs/` directory.
+
+The code is organized into the following directories:
+
+- `src/`: Contains the main source code.
+- `src/core/`: Contains the core functionalities of the firmware.
+- `src/modules/`: Contains the different modules of the firmware.
+- `include/`: Contains the header files.
+- `lib/`: Contains the external libraries.
+
 ## :computer: List of Features
 
 <details>
@@ -259,4 +277,3 @@ Other media can be [found here](./media/).
 ## :construction: Disclaimer
 
 Bruce is a tool for cyber offensive and red team operations, distributed under the terms of the Affero General Public License (AGPL). It is intended for legal and authorized security testing purposes only. Use of this software for any malicious or unauthorized activities is strictly prohibited. By downloading, installing, or using Bruce, you agree to comply with all applicable laws and regulations. This software is provided free of charge, and we do not accept payments for copies or modifications. The developers of Bruce assume no liability for any misuse of the software. Use at your own risk.
-

build.py

@@ -1,3 +1,12 @@
+"""
+This script is a SCons build script for PlatformIO projects.
+
+It provides the following functionalities:
+- Merges the bootloader, partition table, and application binaries into a single firmware binary.
+- Checks if the firmware size exceeds the OTA partition size.
+- Provides a custom target to build the merged firmware.
+- Provides a custom target to upload the firmware without rebuilding.
+"""
 from pathlib import Path
 import csv
 from SCons.Script import Import

include/MenuItemInterface.h

@@ -4,16 +4,51 @@
 #include "core/display.h"
 #include <globals.h>
 
+/**
+ * @brief The MenuItemInterface class.
+ *
+ * This class is an interface for the menu items.
+ */
 class MenuItemInterface {
 public:
+    /**
+     * @brief Destroy the Menu Item Interface object
+     *
+     */
     virtual ~MenuItemInterface() = default;
+    /**
+     * @brief The options menu.
+     */
     virtual void optionsMenu(void) = 0;
+    /**
+     * @brief Draws the icon.
+     *
+     * @param scale The scale of the icon.
+     */
     virtual void drawIcon(float scale = 1) = 0;
+    /**
+     * @brief Draws the icon image.
+     */
     virtual void drawIconImg() = 0;
+    /**
+     * @brief Gets the theme.
+     *
+     * @return bool True if the theme is enabled, false otherwise.
+     */
     virtual bool getTheme() = 0;
 
+    /**
+     * @brief Gets the name.
+     *
+     * @return String The name.
+     */
     String getName() const { return _name; }
 
+    /**
+     * @brief Draws the menu item.
+     *
+     * @param scale The scale of the menu item.
+     */
     void draw(float scale = 1) {
         if (rotation != bruceConfig.rotation) resetCoordinates();
         if (!getTheme()) {
@@ -30,6 +65,11 @@ class MenuItemInterface {
         drawStatusBar();
     }
 
+    /**
+     * @brief Draws the arrows.
+     *
+     * @param scale The scale of the arrows.
+     */
     void drawArrows(float scale = 1) {
         tft.fillRect(arrowAreaX, iconAreaY, arrowAreaW, iconAreaH, bruceConfig.bgColor);
         tft.fillRect(
@@ -83,6 +123,11 @@ class MenuItemInterface {
         );
     }
 
+    /**
+     * @brief Draws the title.
+     *
+     * @param scale The scale of the title.
+     */
     void drawTitle(float scale = 1) {
         int titleY = iconCenterY + iconAreaH / 2 + FG;
 
@@ -112,12 +157,26 @@ class MenuItemInterface {
     int arrowAreaX = BORDER_PAD_X;
     int arrowAreaW = iconAreaX - arrowAreaX;
 
+    /**
+     * @brief Construct a new Menu Item Interface object
+     *
+     * @param name The name of the menu item.
+     */
     MenuItemInterface(const String &name) : _name(name) {}
 
+    /**
+     * @brief Clears the icon area.
+     */
     void clearIconArea(void) {
         tft.fillRect(iconAreaX, iconAreaY, iconAreaW, iconAreaH, bruceConfig.bgColor);
     }
+    /**
+     * @brief Clears the image area.
+     */
     void clearImgArea(void) { tft.fillRect(7, 27, tftWidth - 14, tftHeight - 34, bruceConfig.bgColor); }
+    /**
+     * @brief Resets the coordinates.
+     */
     void resetCoordinates(void) {
         // Recalculate Center and ared due to portrait/landscape changings
         if (tftWidth > tftHeight) {

include/globals.h

@@ -1,3 +1,7 @@
+/**
+ * @file globals.h
+ * @brief This file contains all the global variables and functions.
+ */
 #ifndef __GLOBALS__
 #define __GLOBALS__
 
@@ -93,6 +97,10 @@ extern bool BLEConnected; // inform if BLE is active or not
 
 extern bool gpsConnected; // inform if GPS is active or not
 
+/**
+ * @struct Option
+ * @brief A struct to represent a menu option.
+ */
 struct Option {
     String label;
     std::function<void()> operation;
@@ -110,6 +118,10 @@ struct Option {
         : label(lbl), operation(op), selected(sel), hover(hov), hoverPointer(ptr), hovered(hvrd) {}
 };
 
+/**
+ * @struct keyStroke
+ * @brief A struct to represent a key stroke.
+ */
 struct keyStroke { // DO NOT CHANGE IT!!!!!
     bool pressed = false;
     bool exit_key = false;
@@ -141,6 +153,10 @@ struct keyStroke { // DO NOT CHANGE IT!!!!!
     }
 };
 
+/**
+ * @struct TouchPoint
+ * @brief A struct to represent a touch point.
+ */
 struct TouchPoint {
     bool pressed = false;
     uint16_t x;
@@ -158,6 +174,15 @@ extern TouchPoint touchPoint;
 extern keyStroke KeyStroke;
 extern std::vector<Option> options;
 
+/**
+ * @brief A helper function to create a lambda function from a function pointer.
+ *
+ * @tparam R The return type of the function.
+ * @tparam Args The types of the arguments of the function.
+ * @param callback The function pointer.
+ * @param args The arguments of the function.
+ * @return std::function<void()> The lambda function.
+ */
 template <typename R, typename... Args>
 std::function<void()> lambdaHelper(R (*callback)(Args...), Args... args) {
     return [=]() { (void)callback(args...); };
@@ -210,6 +235,12 @@ extern volatile int EncoderLedChange;
 #endif
 
 extern TaskHandle_t xHandle;
+/**
+ * @brief Checks if a button is pressed.
+ *
+ * @param btn The button to check.
+ * @return bool True if the button is pressed, false otherwise.
+ */
 extern inline bool check(volatile bool &btn) {
 
 #ifndef USE_TFT_eSPI_TOUCH

include/interface.h

@@ -1,68 +1,66 @@
+/**
+ * @file interface.h
+ * @brief This file contains the function declarations for the interface.
+ */
 #pragma once
 #include <Arduino.h>
 #include <vector>
 
-/***************************************************************************************
-** Function name: _setup_gpio()
-** Location: main.cpp
-** Description:   initial setup for the device
-***************************************************************************************/
+/**
+ * @brief Initial setup for the device.
+ * @details This function is located in `main.cpp`.
+ */
 void _setup_gpio();
 
-/***************************************************************************************
-** Function name: _post_setup_gpio()
-** Location: main.cpp
-** Description:   second stage gpio setup to make a few functions work
-***************************************************************************************/
+/**
+ * @brief Second stage gpio setup to make a few functions work.
+ * @details This function is located in `main.cpp`.
+ */
 void _post_setup_gpio();
 
-/***************************************************************************************
-** Function name: getBattery()
-** location: display.cpp
-** Description:   Delivers the battery value from 1-100
-***************************************************************************************/
+/**
+ * @brief Delivers the battery value from 1-100.
+ * @details This function is located in `display.cpp`.
+ * @return The battery value.
+ */
 int getBattery();
 
 
-/*********************************************************************
-** Function: setBrightness
-** location: settings.cpp
-** set brightness value
-**********************************************************************/
+/**
+ * @brief Set brightness value.
+ * @details This function is located in `settings.cpp`.
+ * @param brightval The brightness value.
+ */
 void _setBrightness(uint8_t brightval);
 
 
-/*********************************************************************
-** Function: InputHandler
-** Handles the variables PrevPress, NextPress, SelPress, AnyKeyPress and EscPress
-**********************************************************************/
+/**
+ * @brief Handles the variables PrevPress, NextPress, SelPress, AnyKeyPress and EscPress.
+ */
 void InputHandler(void);
 
 
-/*********************************************************************
-** Function: powerOff
-** location: mykeyboard.cpp
-** Turns off the device (or try to)
-**********************************************************************/
+/**
+ * @brief Turns off the device (or try to).
+ * @details This function is located in `mykeyboard.cpp`.
+ */
 void powerOff();
 
-/*********************************************************************
-** Function: goToDeepSleep
-** location: mykeyboard.cpp
-** Puts the device into DeepSleep
-**********************************************************************/
+/**
+ * @brief Puts the device into DeepSleep.
+ * @details This function is located in `mykeyboard.cpp`.
+ */
 void goToDeepSleep();
 
-/*********************************************************************
-** Function: checkReboot
-** location: mykeyboard.cpp
-** Btn logic to turnoff the device (name is odd btw)
-**********************************************************************/
+/**
+ * @brief Btn logic to turnoff the device (name is odd btw).
+ * @details This function is located in `mykeyboard.cpp`.
+ */
 void checkReboot();
 
-/***************************************************************************************
-** Function name: isCharging()
-** location: interface.cpp
-** Description:   Determines if the device is charging
-***************************************************************************************/
+/**
+ * @brief Determines if the device is charging.
+ * @details This function is located in `interface.cpp`.
+ * @return True if the device is charging, false otherwise.
+ */
 bool isCharging();

include/precompiler_flags.h

@@ -1,3 +1,7 @@
+/**
+ * @file precompiler_flags.h
+ * @brief This file contains all the precompiler flags.
+ */
 // clang-format off
 #pragma once
 /*     This file has the purpose to verify the existence of some default flags      */

include/tftLogger.h

@@ -1,3 +1,7 @@
+/**
+ * @file tftLogger.h
+ * @brief This file contains the tft_logger class.
+ */
 #ifndef __DISPLAY_LOGER
 #define __DISPLAY_LOGER
 #include <precompiler_flags.h> //need to fetch the device Settings that are not in platformio.ini file
@@ -9,6 +13,10 @@
 #include <VectorDisplay.h>
 #define BRUCE_TFT_DRIVER SerialDisplayClass
 #endif
+/**
+ * @enum tftFuncs
+ * @brief An enum to represent the TFT functions.
+ */
 enum tftFuncs : uint8_t { // DO NOT CHANGE THE ORDER, ADD NEW FUNCTIONS TO THE END!!!
     FILLSCREEN,           // 0
     DRAWRECT,             // 1
@@ -41,9 +49,17 @@ enum tftFuncs : uint8_t { // DO NOT CHANGE THE ORDER, ADD NEW FUNCTIONS TO THE E
 #define MAX_LOG_IMAGES 3
 #define MAX_LOG_IMG_PATH 512
 #define LOG_PACKET_HEADER 0xAA
+/**
+ * @struct tftLog
+ * @brief A struct to represent a TFT log.
+ */
 struct tftLog {
     uint8_t data[MAX_LOG_SIZE];
 };
+/**
+ * @class tft_logger
+ * @brief A class to log TFT commands.
+ */
 class tft_logger : public BRUCE_TFT_DRIVER {
 private:
     tftLog log[MAX_LOG_ENTRIES];