From 3608d89bce8397575fd92ab9aecb92dff98bdc76 Mon Sep 17 00:00:00 2001
From: Anja Vujanac <anjavujanacra@gmail.com>
Date: Sat, 21 Sep 2024 00:13:38 +0200
Subject: [PATCH] Documentation of Battery, Buzzer and Capability classes

---
 firmware/Battery.cpp     | 32 ++++++++++++++++++++++++++++++++
 firmware/Battery.h       |  5 +++++
 firmware/Buzzer.cpp      | 25 +++++++++++++++++++++++++
 firmware/Buzzer.h        |  4 ++++
 firmware/Capability.cpp  | 20 ++++++++++++++++++++
 firmware/Capability.h    |  4 ++++
 firmware/Communication.h |  4 ++++
 7 files changed, 94 insertions(+)

diff --git a/firmware/Battery.cpp b/firmware/Battery.cpp
index 809ab70..ec0e9d6 100644
--- a/firmware/Battery.cpp
+++ b/firmware/Battery.cpp
@@ -1,19 +1,51 @@
 #include "Battery.h"
 
+/**
+* Resolution of the ADC (10-bit)
+*/
 const float ADCResolution = 1024.0;
+/**
+* Voltage reference of the Arduino
+*/
 const float arduinoVoltage  = 5.0;
+/**
+* Offset for accurate battery level measurement
+*/
 const float measurementOffset = 0.7;
 
+/**
+* Constructor for the Battery class.
+* 
+* @param pin The pin number used for reading the battery voltage.
+*/
 Battery::Battery(int pin) : pin(pin) {}
 
+/**
+* This method reads the battery level and sends it over the 
+* provided serial.
+* 
+* @param strs Pointer to an array of strings that were used as an input (not used in this method).
+* @param serial Reference to a HardwareSerial object for serial communication.
+*/
 void Battery::decode(String* strs, HardwareSerial& serial) {
     serial.println(getLevel());
 }
 
+/**
+* This method reads the analog value from the specified pin,
+* converts it to a voltage level, and applies an offset for accuracy.
+* 
+* @return The calculated battery voltage level.
+*/
 float Battery::getLevel() {
     return (float(analogRead(pin)) / ADCResolution) * 3 * arduinoVoltage + measurementOffset;
 }
 
+/** 
+* This method returns a character "B" representing the type of the buzzer.
+* 
+* @return A character representing the buzzer type ('B').
+*/
 char Battery::type() {
     return 'B';
 }
diff --git a/firmware/Battery.h b/firmware/Battery.h
index c0163b6..6985d21 100644
--- a/firmware/Battery.h
+++ b/firmware/Battery.h
@@ -5,6 +5,11 @@
 #include <Arduino.h>
 #include <HardwareSerial.h>
 
+/**
+* Battery is a class that looks over the pin off of which we read the voltage that the battery is giving to MILOJE.
+* It is one of the capabilities.
+*/
+
 class Battery : public Capability {
     public:
         Battery(int pin);
diff --git a/firmware/Buzzer.cpp b/firmware/Buzzer.cpp
index 209d916..bee8b98 100644
--- a/firmware/Buzzer.cpp
+++ b/firmware/Buzzer.cpp
@@ -1,15 +1,35 @@
 #include "Buzzer.h"
 
+/**
+* @brief Constructor for the Buzzer class.
+* 
+* @param pin The pin number to which the buzzer is connected.
+*/
 Buzzer::Buzzer(int pin) : pin(pin) {}
 
+/**
+* @brief Sets up the pin mode for the buzzer.
+*/
 void Buzzer::setup() {
     pinMode(pin, OUTPUT);
 }
 
+/**
+* This method is a placeholder for decoding functionality. 
+* Currently, it will buzz at a frequency of 880 Hz.
+* 
+* @param strs Pointer to an array of strings that were used as an input (not used in this method).
+* @param serial Reference to a HardwareSerial object for serial communication (not used in this method).
+*/
 void Buzzer::decode(String* strs, HardwareSerial& serial) {
     buzz(880);
 }
 
+/**
+* This method plays a tone on the buzzer at the given frequency with a melody
+* 
+* @param frequency The frequency of the tone in Hertz.
+*/
 void Buzzer::buzz(int frequency) {
     tone(pin, frequency);
     delay(100);
@@ -19,6 +39,11 @@ void Buzzer::buzz(int frequency) {
     delay(20);
 }
 
+/** 
+* This method returns a character "Z" representing the type of the buzzer.
+* 
+* @return A character representing the buzzer type ('Z').
+*/
 char Buzzer::type() {
     return 'Z';
 }
diff --git a/firmware/Buzzer.h b/firmware/Buzzer.h
index 9bd4c75..3a0be1d 100644
--- a/firmware/Buzzer.h
+++ b/firmware/Buzzer.h
@@ -2,6 +2,10 @@
 #define _BUZZER_H
 #include "Capability.h"
 
+/**
+* Buzzer is a class for the buzzer extension, which is one of the capabilities.
+*/
+
 class Buzzer : public Capability {
     public:
         Buzzer(int pin);
diff --git a/firmware/Capability.cpp b/firmware/Capability.cpp
index 4d7f489..336e081 100644
--- a/firmware/Capability.cpp
+++ b/firmware/Capability.cpp
@@ -1,16 +1,36 @@
 #include "Capability.h"
 
+/**
+* This method is intended for initialization tasks specific to derived classes.
+* It is currently empty and should be overridden in subclasses.
+*/
 void Capability::setup() {}
 
+/**
+* This method is intended for executing the capability's main logic.
+* It is currently empty and should be overridden in subclasses.
+*/
 void Capability::run() {}
 
+/**
+* This method returns the current state of the capability's enabled status.
+* 
+* @return true if the capability is enabled, false otherwise.
+*/
 bool Capability::isEnabled() {
     return enabled;
 }
 
+/**
+* This method sets the enabled state of the capability to true.
+*/
 void Capability::enable() {
     enabled = true;
 }
+
+/**
+* This method sets the enabled state of the capability to false.
+*/
 void Capability::disable() {
     enabled = false;
 }
diff --git a/firmware/Capability.h b/firmware/Capability.h
index 7846d14..a686953 100644
--- a/firmware/Capability.h
+++ b/firmware/Capability.h
@@ -4,6 +4,10 @@
 #include <Arduino.h>
 #include <HardwareSerial.h>
 
+/**
+* Capability is an abstract class for all capabilities.
+*/
+
 class Capability {
     public: 
         virtual char type() = 0;
diff --git a/firmware/Communication.h b/firmware/Communication.h
index 50ab959..8132775 100644
--- a/firmware/Communication.h
+++ b/firmware/Communication.h
@@ -2,6 +2,10 @@
 #define _COMMUNICATION_H
 #include "Capability.h"
 
+/**
+* Communication 
+*/
+
 class Communication
 {
     public: