Merge pull request #252 from HyperloopUPV-H8/features/aidocs

ai documentation

Author: StefanCostea

.vscode/settings.json

@@ -17,5 +17,8 @@
         "**/Makefile": true
     },
     "C_Cpp.default.cppStandard": "c++20",
-    "C_Cpp.default.cStandard": "c17"
+    "C_Cpp.default.cStandard": "c17",
+    "docwriter.style": "Doxygen",
+    "docwriter.progress.trackFunctions": true,
+    "docwriter.progress.trackMethods": true
 }

Src/HALAL/Services/PWM/PhasedPWM/PhasedPWM.cpp

@@ -7,6 +7,11 @@
 
 #include <PWM/PhasedPWM/PhasedPWM.hpp>
 
+/**
+ * The function initializes a PhasedPWM object with a given pin and sets its duty cycle and phase to 0.
+ * 
+ * @param pin The pin to which the PhasedPWM object is being attached.
+ */
 PhasedPWM::PhasedPWM(Pin& pin) {
 	if (not TimerPeripheral::available_pwm.contains(pin)) {
 		ErrorHandler("Pin %s is not registered as an available PWM", pin.to_string());
@@ -30,6 +35,13 @@ PhasedPWM::PhasedPWM(Pin& pin) {
 	phase = 0;
 }
 
+/**
+ * This function sets the duty cycle of a PWM signal and calculates the raw duty and phase values based
+ * on the input duty cycle and phase.
+ * 
+ * @param duty_cycle The duty cycle is a value between 0 and 100 that represents the percentage of time
+ * that the PWM signal is high compared to the total period of the signal.
+ */
 void PhasedPWM::set_duty_cycle(float duty_cycle) {
 	this->duty_cycle = duty_cycle;
 	uint32_t arr = peripheral->handle->Instance->ARR;
@@ -45,12 +57,23 @@ void PhasedPWM::set_duty_cycle(float duty_cycle) {
 	}
 }
 
+/**
+ * This function sets the frequency of a PWM signal using a timer in a microcontroller.
+ * 
+ * @param frequency The desired frequency of the PWM signal in Hertz (Hz).
+ */
 void PhasedPWM::set_frequency(uint32_t frequency) {
 	TIM_TypeDef& timer = *peripheral->handle->Instance;
 	timer.ARR = (HAL_RCC_GetPCLK1Freq()*2 / (timer.PSC+1)) / 2 / frequency;
 	set_duty_cycle(duty_cycle);
 }
 
+/**
+ * This function sets the phase of a PhasedPWM object and updates the duty cycle accordingly.
+ * 
+ * @param phase The "phase" parameter is a floating-point value that represents the phase shift of a
+ * PWM signal. In other words, it determines the timing offset of the PWM waveform relative to its center.
+ */
 void PhasedPWM::set_phase(float phase) {
 	this->phase = phase;
 	set_duty_cycle(duty_cycle);

Src/ST-LIB_LOW/StateMachine/StateMachine.cpp

@@ -20,11 +20,26 @@ void State::exit() {
 	}
 }
 
+/**
+ * This is a constructor for a StateMachine object that initializes the initial state and creates a
+ * State object for it.
+ * 
+ * @param initial_state The initial state parameter is an unsigned 8-bit integer that represents the
+ * starting state of the state machine.
+ */
 StateMachine::StateMachine(uint8_t initial_state) :
 	initial_state(initial_state), current_state(initial_state) {
 	states[initial_state] = State();
 }
 
+/**
+ * The function adds a state to a state machine and sets it as the initial and current state if it is
+ * the first state added.
+ * 
+ * @param state The state to be added to the state machine.
+ * 
+ * @return The function does not return anything. It has a void return type.
+ */
 void StateMachine::add_state(uint8_t state) {
 	if (states.contains(state)) {
 		ErrorHandler("The state %d is already added", state);
@@ -38,6 +53,13 @@ void StateMachine::add_state(uint8_t state) {
 	states[state];
 }
 
+/**
+ * This function adds an action to be executed when entering the current state of a state machine.
+ * 
+ * @param action The parameter "action" is a function pointer to a function that takes no arguments and
+ * returns nothing (void). It represents an action that should be executed when the current state of
+ * the state machine is entered.
+ */
 void StateMachine::add_enter_action(function<void()> action) {
 	if (not current_state) {
 		ErrorHandler("The state machine does not have a current state");
@@ -46,6 +68,15 @@ void StateMachine::add_enter_action(function<void()> action) {
 	states[current_state].on_enter_actions.push_back(action);
 }
 
+/**
+ * This function adds an action to be executed when entering a specific state in a state machine.
+ * 
+ * @param action The action parameter is a function pointer to a function that takes no arguments and
+ * returns nothing. This function will be executed when the state machine transitions to the state
+ * specified by the state parameter.
+ * @param state The state parameter is an unsigned 8-bit integer that represents the state to which the
+ * enter action is being added.
+ */
 void StateMachine::add_enter_action(function<void()> action, uint8_t state) {
 	if (not states.contains(state)) {
 		ErrorHandler("The state %d is not added to the state machine", state);
@@ -54,13 +85,31 @@ void StateMachine::add_enter_action(function<void()> action, uint8_t state) {
 	states[state].on_enter_actions.push_back(action);
 }
 
+/**
+ * This function adds an exit action to the current state of a state machine.
+ * 
+ * @param action `action` is a function pointer to a function that takes no arguments and returns
+ * nothing (`void`). It represents an action that should be executed when the state machine exits the
+ * current state and transitions to a new state. The `add_exit_action` function adds this action to the
+ * list of exit actions for
+ */
 void StateMachine::add_exit_action(function<void()> action) {
 	if (not current_state) {
 		ErrorHandler("The state machine does not have a current state");
 		return;
 	}
 	states[current_state].on_exit_actions.push_back(action);
 }
+
+/**
+ * This function adds an exit action to a specific state in a state machine.
+ * 
+ * @param action The action parameter is a function pointer to a function that takes no arguments and
+ * returns nothing. This function represents the action that will be executed when the state machine
+ * exits the specified state.
+ * @param state The state parameter is an unsigned 8-bit integer that represents the state to which the
+ * exit action is being added.
+ */
 void StateMachine::add_exit_action(function<void()> action, uint8_t state) {
 	if (not states.contains(state)) {
 		ErrorHandler("The state %d is not added to the state machine");
@@ -69,6 +118,17 @@ void StateMachine::add_exit_action(function<void()> action, uint8_t state) {
 	states[state].on_exit_actions.push_back(action);
 }
 
+/**
+ * This function adds a transition between two states in a state machine.
+ * 
+ * @param old_state The current state of the state machine before the transition occurs. It is
+ * represented as an unsigned 8-bit integer (uint8_t).
+ * @param new_state The new state to transition to. It is of type uint8_t.
+ * @param transition The parameter "transition" is a function pointer to a boolean function that takes
+ * no arguments. This function represents the condition that must be met in order for the state machine
+ * to transition from the old_state to the new_state. If the condition is true, the transition will
+ * occur. If the condition is false
+ */
 void StateMachine::add_transition(uint8_t old_state, uint8_t new_state,
 		function<bool()> transition) {
 	if (not states.contains(old_state)) {
@@ -83,6 +143,14 @@ void StateMachine::add_transition(uint8_t old_state, uint8_t new_state,
 	transitions[old_state][new_state] = transition;
 }
 
+/**
+ * The function adds a nested state machine to the current state machine and clears any timed actions
+ * associated with the nested state machine's current state if it is not the current state.
+ * 
+ * @param state_machine A reference to a StateMachine object that is being added as a nested state
+ * machine to the current StateMachine object.
+ * @param state The state to which the nested state machine is being added.
+ */
 void StateMachine::add_state_machine(StateMachine& state_machine, uint8_t state) {
 	nested_state_machine[state] = &state_machine;
 
@@ -99,6 +167,10 @@ void StateMachine::add_state_machine(StateMachine& state_machine, uint8_t state)
 	}
 }
 
+/**
+ * The function checks for state transitions and changes the current state if necessary, and also
+ * checks for transitions in a nested state machine if applicable.
+ */
 void StateMachine::check_transitions() {
 	for (auto const state_transition : transitions[current_state]) {
 		if (state_transition.second()) {