Added comments to all functions

src/main.cpp

@@ -2,8 +2,18 @@
 #include <serialConnector.h>
 
 SerialConnector *conn = new SerialConnector();
+
+/**
+ * Handler called when calibration begin/interrupt commands are received.
+ * Declared before setup so it can be registered as a callback.
+ * @param args Arguments string passed from the incoming command.
+ */
 void calibrationBegin(String args);
 
+/**
+ * Setup is called once when the Arduino boots.
+ * Configure pin modes, initialize Serial, and register callbacks here.
+ */
 void setup()
 {
     pinMode(11, OUTPUT);
@@ -19,6 +29,10 @@ void setup()
     conn->onCalibrationInterupt(&calibrationBegin);
 }
 
+/**
+ * Main loop called repeatedly by the Arduino runtime.
+ * It processes incoming serial messages and checks input pins to send commands.
+ */
 void loop()
 {
     conn->cycle();
@@ -41,6 +55,10 @@ void loop()
     delay(300);
 }
 
+/**
+ * Blink an output pin a number of times based on the provided argument.
+ * @param args A string containing a numeric value indicating how many blinks to perform.
+ */
 void calibrationBegin(String args)
 {
     for (int i = 0; i < args.toInt(); i++)

src/serialConnector.cpp

@@ -11,8 +11,10 @@
  *
  */
 
-// Main polling loop: read incoming serial frames, validate the check-bit,
-// acknowledge valid messages and dispatch handlers based on the command.
+/**
+ * Periodically called to process incoming serial data and dispatch events.
+ * Should be called frequently from the main loop.
+ */
 void SerialConnector::cycle()
 {
     if (Serial.available() > 3)
@@ -44,8 +46,11 @@ void SerialConnector::cycle()
     }
 }
 
-// Convert each character in `cmd` into its ASCII hexadecimal representation
-// and return the concatenated hex string. Example: "A" -> "41".
+/**
+ * Convert a string into its hexadecimal representation.
+ * @param cmd Input string to convert.
+ * @return Hexadecimal representation of the input string.
+ */
 String SerialConnector::stringToHex(String cmd)
 {
     int hex_dec;
@@ -83,9 +88,11 @@ String SerialConnector::stringToHex(String cmd)
     return output;
 }
 
-// Produce a numeric check value for `cmd` by converting characters to
-// their hexadecimal digits and summing their digit characters into an
-// integer representation. This mirrors the protocol used for check-bits.
+/**
+ * Convert a string into a numeric checksum used by the protocol.
+ * @param cmd Input string to convert.
+ * @return Integer checksum computed from the input string.
+ */
 int SerialConnector::stringToCheckNum(String cmd)
 {
     int hex_dec;
@@ -123,7 +130,12 @@ int SerialConnector::stringToCheckNum(String cmd)
     return output;
 }
 
-// Return the index of `ch` inside `str`. Returns -1 if `ch` is not found.
+/**
+ * Find the index of a character inside a string.
+ * @param ch Character to search for.
+ * @param str String to search within.
+ * @return Index of the character if found, -1 otherwise.
+ */
 int SerialConnector::getCharIndex(char ch, String str)
 {
     for (int i = 0; i < str.length(); i++)
@@ -135,16 +147,23 @@ int SerialConnector::getCharIndex(char ch, String str)
     return -1;
 }
 
-// Extract the command portion from an incoming framed message. The
-// protocol format is: <CMD>#<ARGS>#<CHECK>@ — this returns <CMD>.
+/**
+ * Extract the command portion from an incoming raw message.
+ * The message format is expected to be: CMD#ARGS#CHECK@ (terminator '@').
+ * @param incomming Raw incoming message string.
+ * @return The command portion of the incoming message.
+ */
 String SerialConnector::getCommandFromIncomming(String incomming)
 {
     int cmdEnd = getCharIndex('#', incomming);
     return incomming.substring(0, cmdEnd);
 }
 
-// Extract the arguments portion from an incoming message: returns the
-// text between the first and second '#' characters.
+/**
+ * Extract the arguments portion from an incoming raw message.
+ * @param incomming Raw incoming message string.
+ * @return The arguments portion of the incoming message.
+ */
 String SerialConnector::getArgsFromIncomming(String incomming)
 {
     int cmdEnd = getCharIndex('#', incomming);
@@ -155,8 +174,11 @@ String SerialConnector::getArgsFromIncomming(String incomming)
     return afterCmd.substring(0, cmdArgsEnd);
 }
 
-// Extract the check-bit (final field) from an incoming message: the text
-// after the second '#' character (up to the '@' frame terminator).
+/**
+ * Extract the check bit (checksum) portion from an incoming raw message.
+ * @param incomming Raw incoming message string.
+ * @return The check bit (as string) of the incoming message.
+ */
 String SerialConnector::getCheckBitFromIncomming(String incomming)
 {
     int cmdEnd = getCharIndex('#', incomming);
@@ -167,8 +189,13 @@ String SerialConnector::getCheckBitFromIncomming(String incomming)
     return afterCmd.substring(cmdArgsEnd + 1, afterCmd.length());
 }
 
-// Verify that `checkBit` equals the computed check for `<cmd>#<args>`.
-// Returns true when they match, false otherwise.
+/**
+ * Verify that the provided checkBit matches the computed checksum for cmd and args.
+ * @param cmd Command portion.
+ * @param args Arguments portion.
+ * @param checkBit Integer check bit to verify against.
+ * @return true if checksum matches, false otherwise.
+ */
 bool SerialConnector::verifyCheckBit(String cmd, String args, int checkBit)
 {
     String toCheck = cmd + "#" + args;
@@ -179,15 +206,20 @@ bool SerialConnector::verifyCheckBit(String cmd, String args, int checkBit)
         return false;
 }
 
-// Send a repeat (RPT) frame asking the remote to resend the last message.
+/**
+ * Send a repeat request to the other side.
+ * This will send the protocol message that instructs the peer to re-send.
+ */
 void SerialConnector::repeat()
 {
     String cmd = "RPT##410@";
     Serial.print(cmd);
 }
 
-// Send an acknowledgement (ACKG) frame that includes the original
-// command's check-bit so the sender can confirm delivery.
+/**
+ * Send an acknowledgement for a received message.
+ * @param checkBit Check bit value to include in the acknowledgement.
+ */
 void SerialConnector::acknowledge(int checkBit)
 {
     String cmd = "ACKG";
@@ -197,8 +229,12 @@ void SerialConnector::acknowledge(int checkBit)
     Serial.print(final);
 }
 
-// Build and send a framed command with `cmd` and `args`. Appends a computed
-// check-bit and frame terminator, then waits for follow-up (ack/repeat).
+/**
+ * Send a command using the defined protocol. The function composes the message,
+ * computes the checksum and sends the final string terminated with '@'.
+ * @param cmd Command name (e.g., "READ").
+ * @param args Arguments for the command.
+ */
 void SerialConnector::sendCommand(String cmd, String args)
 {
     String toSend = cmd + "#" + args;
@@ -209,9 +245,10 @@ void SerialConnector::sendCommand(String cmd, String args)
     afterSendCheck(final);
 }
 
-// After sending a command, read the next frame and handle either a
-// repeat (RPT) request or an acknowledgement (ACKG). For RPT, resend the
-// original command. For ACKG, verify the returned check-bit matches.
+/**
+ * After sending a command, read for the peer's reply (ACKG or RPT) and act accordingly.
+ * @param cmd The full command string that was sent (including checksum and terminator).
+ */
 void SerialConnector::afterSendCheck(String cmd)
 {
     String raw = Serial.readStringUntil('@');
@@ -239,29 +276,11 @@ void SerialConnector::afterSendCheck(String cmd)
     }
 }
 
-// Register a callback to be invoked when an acknowledgement frame is
-// received. The callback receives the acknowledgement's args string.
-void SerialConnector::onAcknowledge(void (*handler)(String args))
-{
-    acknowledgeHandler = handler;
-}
-
-// Register a callback to be invoked when a repeat (RPT) frame is
-// received. The handler receives the repeat frame's args.
-void SerialConnector::onRepeat(void (*handler)(String args))
-{
-    repeatHandler = handler;
-}
-
-// Register a callback for the 'CAL-BGN' command. The handler receives the
-// calibration arguments string when calibration begins.
 void SerialConnector::onCalibrationBegin(void (*handler)(String args))
 {
     calibrationBeginHandler = handler;
 }
 
-// Register a callback for the 'CAL-INT' command. The handler receives the
-// calibration interrupt arguments string when an interrupt occurs.
 void SerialConnector::onCalibrationInterupt(void (*handler)(String args))
 {
     calibrationInteruptHandler = handler;