Format and/or add documentation comments

Author: efondere

README.md

@@ -3,7 +3,7 @@
 ## Setup
 
 1. Install the [Arduino IDE](https://www.arduino.cc/en/software). Use the new 2.0.0 version if possible as it is easier to work with.
-2. Install CrcLib, ArduinoExtra (see programming resources document) and [Paul Stoffergen's Encoder library](https://www.arduino.cc/reference/en/libraries/encoder/)
+2. Install CrcLib, ArduinoExtra, and [Paul Stoffergen's Encoder library](https://www.arduino.cc/reference/en/libraries/encoder/)
 3. Clone this repository in the User/Documents/Arduino/libraries/ folder (or equivalent on Mac).
 4. Open the Arduino IDE and create a new project. Select the `Arduino Mega or Mega 2560` board. Write `#include <RobotUtils.h>` at the top of the file and press verify to make sure everything is installed properly.
 5. Open the cloned repository in VSCode or another text editor/IDE (make sure you don't commit your project files on accident). You can install an editorconfig extension for automatic file formatting ([VSCode Example](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig)).

RobotUtils/Controller.h

@@ -1,12 +1,10 @@
 /**
  * @file Controller.h
  * @author Gabriel Saberian
- * @brief Controller header file for Vanier Robotics' RobotUtils library, controls the robot by pressing
- * digital and analog buttons on a controller.
+ * @brief Controller class used to manage all sorts of inputs
  *
  * @copyright Copyright (c) 2023 Vanier Robotics (MIT License)
  */
-
 #include <ArduinoExtra.h>
 #include <CrcLib.h>
 
@@ -16,98 +14,144 @@
 namespace rou
 {
 
+/**
+ * @brief Controller class, which can be used to manage the various inputs for a robot
+ *
+ */
 class Controller
 {
-	// Structure that contains the variables and fuctions for the digital binding
+	/**
+	 * @brief Structure that contains the variables and function for a digital binding
+	 *
+	 */
 	struct DigitalBinding
 	{
-		Crc::BUTTON 				buttonID; //variable of type BUTTON (from CRC lib) that stores a specific button
-		aex::Function<void(bool)>	callback; //pointer function used to do some action with a digital button
+		Crc::BUTTON 				buttonID; ///< variable of type BUTTON (from CrcLib) that stores a specific button
+		aex::Function<void(bool)>	callback; ///< pointer to the function called when the binding changes state
 	};
 
-	//Structure that contains the variables and fuctions for the toggle binding
+	/**
+	 * @brief Structure that contains the variables and function for a toggle binding
+	 *
+	 */
 	struct ToggleBinding
 	{
-		Crc::BUTTON					buttonID; //variable of type BUTTON (from CRC lib) that stores a specific button
-		aex::Function<void(bool)>	callback; //pointer function used to do some action with a toggle action
+		Crc::BUTTON					buttonID; ///< variable of type BUTTON (from CrcLib) that stores a specific button
+		aex::Function<void(bool)>	callback; ///< pointer to the function called when the binding changes state
 
-		bool isToggled; //boolean variable that stores the state of the button (Toggled = true and not toggled = false)
-		// boolean variable that stores the last value of a button and used to defined the isToggled value
-		//(if lastValue = true, then the last button was pressed and if lastValue = false, then the last button wasn't pressed)
-		bool lastValue;
+		bool isToggled; ///< stores the state of the button
+		bool lastValue; ///< boolean variable that keeps track of the previous value of a button
 	};
 
-	//Structure that contains the variables and fuctions for the analog binding
+	/**
+	 * @brief Structure that contains the variables and function for an analog binding
+	 *
+	 */
 	struct AnalogBinding
 	{
-		Crc::ANALOG 				analogID; //variable of type ANALOG (from CRC lib) that stores a specific button
-		aex::Function<void(int8_t)>	callback; //pointer function used to do some action with an analog button
+		Crc::ANALOG 				analogID; ///< variable of type ANALOG (from CrcLib) that stores a specific button
+		aex::Function<void(int8_t)>	callback; ///< pointer to the function called when the binding changes state
 	};
 
-	//Structure that contains the variables and fuctions for the digital sensor binding
+	/**
+	 * @brief Structure that contains the variables and functions for a digital sensor binding
+	 *
+	 */
 	struct DigitalSensorBinding
 	{
-		uint8_t						pin; //variable of type uint8_t that stores the number of the pin on the crcDuino board change type
-		aex::Function<void(bool)>	callback;
+		uint8_t						pin;      ///< the pin number from Crclib
+		aex::Function<void(bool)>	callback; ///< pointer to the function called when the binding changes state
 	};
 
-	//Structure that contains the variables and fuctions for the analog sensor binding
+	/**
+	 * @brief Structure that contains the variables and functions for an analog sensor binding
+	 *
+	 */
 	struct AnalogSensorBinding
 	{
-		uint8_t								pin; //variable of type uint8_t that stores the number of the pin on the crcDuino board change type
-		aex::Function<void(unsigned int)>	callback;
+		uint8_t								pin;      ///< the pin number from Crclib
+		aex::Function<void(unsigned int)>	callback; ///< pointer to the function called when the binding changes state
 	};
 
 public:
-	//callback functions (pointer functions) of the different structures
-	//callback function for digital bindings
+	/**
+	 * @brief Setup a callback function for a digital binding
+	 *
+	 * @param buttonID The BUTTON to which the binding is assigned
+	 * @param callback Pointer to the function that will be called when this binding is updated
+	 */
 	void digitalBind(Crc::BUTTON buttonID, aex::Function<void(bool)> callback)
 	{
 		m_digitalBindings.pushBack({buttonID, callback});
 	}
 
-	//callback function for toggle bindings
+	/**
+	 * @brief Setup a callback function for a toggle binding
+	 *
+	 * @param buttonID The BUTTON to which the binding is assigned
+	 * @param callback Pointer to the function that will be called when this binding is updated
+	 */
 	void toggleBind(Crc::BUTTON buttonID, aex::Function<void(bool)> callback)
 	{
 		m_toggleBindings.pushBack({buttonID, callback, false, false});
 	}
 
-	//callback function for analog bindings
+	/**
+	 * @brief Setup a callback function for an analog binding
+	 *
+	 * @param analogID The ANALOG input to which the binding is assigned
+	 * @param callback Pointer to the function that will be called when this binding is updated
+	 */
 	void analogBind(Crc::ANALOG analogID, aex::Function<void(int8_t)> callback)
 	{
 		m_analogBindings.pushBack({analogID, callback});
 	}
 
-	//callback function for digital sensor bindings
+	/**
+	 * @brief Setup a callback function for a digital sensor binding
+	 *
+	 * @param pin The CrcLib pin number to which the sensor is connected
+	 * @param callback Pointer to the function that will be called when this binding is updated
+	 */
 	void digitalSensorBind(uint8_t pin, aex::Function<void(bool)> callback)
 	{
 		m_digitalSensorBindings.pushBack({pin, callback});
 	}
 
-	//callback function for analog sensor binding
+	/**
+	 * @brief Setup a callback function for an analog sensor binding
+	 *
+	 * @param pin The CrcLib pin number to which the sensor is connected
+	 * @param callback Pointer to the function that will be called when this binding is updated
+	 */
 	void analogSensorBind(uint8_t pin, aex::Function<void(unsigned int)> callback)
 	{
 		m_analogSensorBindings.pushBack({pin, callback});
 	}
 
+	/**
+	 * @brief Update all the bindings and call the required callbacks
+	 *
+	 */
 	void update()
 	{
-		//For each frame, verify which button are pressed and call the corresponding methods
-		//Digital Bindings verification
+		// For each frame, verify which button are pressed and call the corresponding methods
+
+		// Digital Bindings verification
 		for (int i = 0; i < m_digitalBindings.getSize(); i++)
 		{
 			m_digitalBindings[i].callback(
 				Crc::CrcLib::ReadDigitalChannel(m_digitalBindings[i].buttonID));
 		}
 
-		//Analog Bindings verification
+		// Analog Bindings verification
 		for (int i = 0; i < m_analogBindings.getSize(); i++)
 		{
 			m_analogBindings[i].callback(
 				Crc::CrcLib::ReadAnalogChannel(m_analogBindings[i].analogID));
 		}
 
-		//Toggle Bindings verification
+		// Toggle Bindings verification
 		for (int i = 0; i < m_toggleBindings.getSize(); i++)
 		{
 			bool status = Crc::CrcLib::ReadDigitalChannel(m_toggleBindings[i].buttonID);
@@ -120,14 +164,14 @@ class Controller
 			m_toggleBindings[i].lastValue = status;
 		}
 
-		//Digital Sensor Bindings verification
+		// Digital Sensor Bindings verification
 		for (int i = 0; i < m_digitalSensorBindings.getSize(); i++)
 		{
 			m_digitalSensorBindings[i].callback(
 				(Crc::CrcLib::GetDigitalInput(m_digitalSensorBindings[i].pin) == HIGH));
 		}
 
-		//Analog Sensor Bindings verification
+		// Analog Sensor Bindings verification
 		for (int i = 0; i < m_analogSensorBindings.getSize(); i++)
 		{
 			m_analogSensorBindings[i].callback(
@@ -136,12 +180,11 @@ class Controller
 	}
 
 private:
-	//Vector arrays
-	aex::Vector<DigitalBinding>			m_digitalBindings; //Create a vector array of type DigitalBinding
-	aex::Vector<ToggleBinding>			m_toggleBindings; //Create a vector array of type ToggleBinding
-	aex::Vector<AnalogBinding>			m_analogBindings; //Create a vector array of type AnalogBinding
-	aex::Vector<DigitalSensorBinding>	m_digitalSensorBindings; //Create a vector array of type DigitalSensorBinding
-	aex::Vector<AnalogSensorBinding>	m_analogSensorBindings; //Create a vector array of type AnalogBinding
+	aex::Vector<DigitalBinding>			m_digitalBindings;       ///< Vector of DigitalBinding's which were created
+	aex::Vector<ToggleBinding>			m_toggleBindings;        ///< Vector of ToggleBinding's which were created
+	aex::Vector<AnalogBinding>			m_analogBindings;        ///< Vector of AnalogBinding's which were created
+	aex::Vector<DigitalSensorBinding>	m_digitalSensorBindings; ///< Vector of DigitalSensorBinding's which were created
+	aex::Vector<AnalogSensorBinding>	m_analogSensorBindings;  ///< Vector of AnalogSensorBinding's which were created
 };
 
 } // rou

RobotUtils/Handle.h

@@ -1,11 +1,10 @@
 /**
  * @file Handle.h
  * @author Jiucheng Zang
- * @brief Handle class
+ * @brief Base Handle class
  *
  * @copyright Copyright (c) 2023 Vanier Robotics (MIT License)
  */
-
 #ifndef _INCLUDE_ROU_HANDLE_H_
 #define _INCLUDE_ROU_HANDLE_H_
 
@@ -15,7 +14,7 @@ namespace rou
 class HandleManager;
 
 /**
- * @brief Handle class
+ * @brief Base Handle class
  *
  */
 class Handle
@@ -24,19 +23,21 @@ class Handle
 	friend class HandleManager;
 
 	/**
-	 * @brief Check if Handle is available for now
+	 * @brief Check if Handle is currently available
 	 *
-	 * @return bool m_available value if available
+	 * @return true the handle is available
+	 * @return false the handle has already been used
 	 */
 	bool isAvailable()
 	{
 		return m_isAvailable;
 	}
 
 	/**
-	 * @brief Check if this handle be used. If not add it up and return true, else return false do nothing.
+	 * @brief Check if this handle be used. If not, switch it to unavailable return true, else return false do nothing.
 	 *
-	 * @return bool temp_available value if use success
+	 * @return true the handle can be used
+	 * @return false the handle has been previously used and is no longer avaiable
 	 */
 	bool use()
 	{
@@ -47,7 +48,7 @@ class Handle
 	}
 
 	/**
-	 * @brief Release this handle
+	 * @brief Release this handle, making it available again
 	 *
 	 */
 	void release()
@@ -58,14 +59,14 @@ class Handle
 protected:
 	/**
 	 * @brief Setup the handle (ie. initialize the pin, etc.)
-	 * 
+	 *
 	 * Some handles do not require any setup, which is why the base defaults to an empty method
 	 */
 	virtual void setup()
 	{
 	}
 
-	bool m_isAvailable = true;
+	bool m_isAvailable = true; ///< stores whether the handle can be used or has already been used
 };
 
 } // namespace rou

RobotUtils/HandleManager.h

@@ -1,11 +1,10 @@
 /**
  * @file HandleManager.h
  * @author Jiucheng Zang
- * @brief Handle Manager class
+ * @brief Manages the use of all handles
  *
  * @copyright Copyright (c) 2023 Vanier Robotics (MIT License)
  */
-
 #ifndef _INCLUDE_ROU_HANDLE_MANAGER_H_
 #define _INCLUDE_ROU_HANDLE_MANAGER_H_
 
@@ -16,15 +15,14 @@ namespace rou
 {
 
 /**
- * @brief Handle Manager class
+ * @brief HandleManager class, which controls the use of all individual handles
  *
- * @extends Handle class
  */
 class HandleManager
 {
 public:
 	/**
-	 * @brief Release all the Handle in the Handle Manager
+	 * @brief Release all the handles stored in the handle manager
 	 *
 	 */
 	void releaseAll()
@@ -38,7 +36,9 @@ class HandleManager
 	/**
 	 * @brief Add different Handle into Handle Manager Class
 	 *
-	 * @param handle Different types of handle
+	 * @param handle a pointer to any handle
+	 *
+	 * All handles must be added to the handle manager
 	 */
 	void addHandle(Handle* handle)
 	{
@@ -47,7 +47,7 @@ class HandleManager
 	}
 
 private:
-	aex::Vector<Handle*> m_handles;
+	aex::Vector<Handle*> m_handles; ///< Vector of ALL handles used by the robot
 };
 
 } // namespace rou

RobotUtils/Handles.h

@@ -5,7 +5,6 @@
  *
  * @copyright Copyright (c) 2023 Vanier Robotics (MIT License)
  */
-
 #ifndef _INCLUDE_ROU_HANDLES_H_
 #define _INCLUDE_ROU_HANDLES_H_