Merge pull request 'Added build action for documentation' (#3) from development into main

Reviewed-on: #3

.gitea/workflows/build-docs.yaml

@@ -0,0 +1,20 @@
+name: Generate Documentation
+
+on:
+  push:
+    branches:
+      - development
+
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: mattnotmitt/doxygen-action@v1.9.5
+        with:
+          working-directory: './'
+          doxyfile-path: './Doxyfile'
+        name: Build Doxygen Documentation

.gitignore

@@ -3,3 +3,4 @@
 .vscode/c_cpp_properties.json
 .vscode/launch.json
 .vscode/ipch
+docs/

include/staffFunctions.h

@@ -1,4 +1,17 @@
 #pragma once
 
+/**
+ * @brief Used to increase the maximum staff volume
+ *
+ * @param maxVolume Pointer to the variable used to keep track of staff volume
+ */
 void staffVolumeUp(int *maxVolume);
+
+/**
+ * @brief Used to decrease the maximum staff volume. If the max volume is set lower than what the current user volume is, then the user volume will also be lowered.
+ *
+ * @param maxVolume Variable used to keep track of the max volume
+ * @param userVolume Pointer to the variable used to keep track of the user volume
+ * @param oldUserVolume Pointer to the variable used to keep track of the user volume when in mute or lowered
+ */
 void staffVolumeDown(int maxVolume, int *userVolume, int *oldUserVolume);

include/userFunctions.h

@@ -1,6 +1,40 @@
 #pragma once
 
+/**
+ * @brief This function is used to increase the volume
+ *
+ * @param userVolume Pointer to the variable used to keep track of the current user volume. It is being passed in so the function can increment it with the potentiometer steps.
+ * @param oldUserVolume Pointer to the variable used to keep track of the user volume while muted or lowered. It is being passed in so the function can increment it with the potentiometer steps.
+ * @param maxVolume The highest point that the volume can be set to.
+ *
+ */
 void volumeUp(int *userVolume, int *oldUserVolume, int maxVolume);
+
+/**
+ * This function is used to decrease the volume
+ *
+ * @param userVolume Pointer to the variable used to keep track of the current user volume. It is being passed in so the function can increment it with the potentiometer steps.
+ * @param oldUserVolume Pointer to the variable used to keep track of the user volume while muted or lowered. It is being passed in so the function can increment it with the potentiometer steps.
+ *
+ */
 void volumeDown(int *userVolume, int *oldUserVolume);
+
+/**
+ * This function is used to significantly lower the volume. If the function is called while in a lowered state it will revert the volume to what it previously was.
+ *
+ * @param userVolume Pointer to the variable used to keep track of the current user volume. It is being passed in so the function can increment it with the potentiometer steps.
+ * @param oldUserVolume Pointer to the variable used to keep track of the user volume while muted or lowered. It is being passed in so the function can increment it with the potentiometer steps.
+ * @param maxVolume The highest point that the volume can be set to.
+ *
+ */
 void lowerVolume(int *userVolume, int *oldUserVolume, int maxVolume);
+
+/**
+ * This function is used to mute the volume. If the function is called while in a muted state it will revert the volume to what it previously was.
+ *
+ * @param userVolume Pointer to the variable used to keep track of the current user volume. It is being passed in so the function can increment it with the potentiometer steps.
+ * @param oldUserVolume Pointer to the variable used to keep track of the user volume while muted or lowered. It is being passed in so the function can increment it with the potentiometer steps.
+ * @param maxVolume The highest point that the volume can be set to.
+ *
+ */
 void mute(int *userVolume, int *oldUserVolume, int maxVolume);

src/staffFunctions.cpp

@@ -1,7 +1,23 @@
+/**
+ * @file staffFunctions.cpp
+ * @author Lyubomir Penev
+ * @brief Here are all the implementations of the staff functions
+ * @version 1.0
+ * @date 2025-10-23
+ *
+ * @copyright Copyright (c) 2025
+ *
+ */
+
 #include <staffFunctions.h>
 #include <constants.h>
 #include <potControlls.h>
 
+/**
+ * @brief Used to increase the maximum staff volume
+ * 
+ * @param maxVolume Pointer to the variable used to keep track of staff volume
+ */
 void staffVolumeUp(int *maxVolume)
 {
     if (*maxVolume < 64)
@@ -10,6 +26,13 @@ void staffVolumeUp(int *maxVolume)
     }
 }
 
+/**
+ * @brief Used to decrease the maximum staff volume. If the max volume is set lower than what the current user volume is, then the user volume will also be lowered.
+ * 
+ * @param maxVolume Variable used to keep track of the max volume
+ * @param userVolume Pointer to the variable used to keep track of the user volume
+ * @param oldUserVolume Pointer to the variable used to keep track of the user volume when in mute or lowered
+ */
 void staffVolumeDown(int maxVolume, int *userVolume, int *oldUserVolume)
 {
     if (maxVolume > STAFF_STEPS)

src/userFunctions.cpp

@@ -1,7 +1,24 @@
+/**
+ * @file userFunctions.cpp
+ * @author Lyubomir Penev
+ * @brief Here are all the implementations for the user functions.
+ * @version 1.0
+ * @date 2025-10-23
+ *
+ */
+
 #include <userFunctions.h>
 #include <constants.h>
 #include <potControlls.h>
 
+/**
+ * This function is used to mute the volume. If the function is called while in a muted state it will revert the volume to what it previously was.
+ *
+ * @param userVolume Pointer to the variable used to keep track of the current user volume. It is being passed in so the function can increment it with the potentiometer steps.
+ * @param oldUserVolume Pointer to the variable used to keep track of the user volume while muted or lowered. It is being passed in so the function can increment it with the potentiometer steps.
+ * @param maxVolume The highest point that the volume can be set to.
+ *
+ */
 void mute(int *userVolume, int *oldUserVolume, int maxVolume)
 {
     // Check if we are in a muted state
@@ -43,6 +60,14 @@ void mute(int *userVolume, int *oldUserVolume, int maxVolume)
     }
 }
 
+/**
+ * This function is used to significantly lower the volume. If the function is called while in a lowered state it will revert the volume to what it previously was.
+ *
+ * @param userVolume Pointer to the variable used to keep track of the current user volume. It is being passed in so the function can increment it with the potentiometer steps.
+ * @param oldUserVolume Pointer to the variable used to keep track of the user volume while muted or lowered. It is being passed in so the function can increment it with the potentiometer steps.
+ * @param maxVolume The highest point that the volume can be set to.
+ *
+ */
 void lowerVolume(int *userVolume, int *oldUserVolume, int maxVolume)
 {
     // Check if we volume is already lowered
@@ -85,6 +110,14 @@ void lowerVolume(int *userVolume, int *oldUserVolume, int maxVolume)
     }
 }
 
+/**
+ * This function is used to increase the volume
+ *
+ * @param userVolume Pointer to the variable used to keep track of the current user volume. It is being passed in so the function can increment it with the potentiometer steps.
+ * @param oldUserVolume Pointer to the variable used to keep track of the user volume while muted or lowered. It is being passed in so the function can increment it with the potentiometer steps.
+ * @param maxVolume The highest point that the volume can be set to.
+ *
+ */
 void volumeUp(int *userVolume, int *oldUserVolume, int maxVolume)
 {
     if ((*userVolume + USER_STEPS) > maxVolume)
@@ -109,6 +142,13 @@ void volumeUp(int *userVolume, int *oldUserVolume, int maxVolume)
     }
 }
 
+/**
+ * This function is used to decrease the volume
+ *
+ * @param userVolume Pointer to the variable used to keep track of the current user volume. It is being passed in so the function can increment it with the potentiometer steps.
+ * @param oldUserVolume Pointer to the variable used to keep track of the user volume while muted or lowered. It is being passed in so the function can increment it with the potentiometer steps.
+ *
+ */
 void volumeDown(int *userVolume, int *oldUserVolume)
 {
     if ((*userVolume - USER_STEPS) < 0)