From e9cbe54ecae1c765b60fbb25cfdb9effe31f2e4d Mon Sep 17 00:00:00 2001
From: Jm Casler <jm@casler.org>
Date: Wed, 26 Jul 2023 16:48:04 -0700
Subject: [PATCH] add more documentaiton

---
 src/OSTimer.cpp  | 10 ++++++++++
 src/Power.cpp    | 16 ++++++++++++++++
 src/PowerFSM.cpp |  9 +++++++++
 src/memGet.cpp   | 27 +++++++++++++++++++++++++++
 src/xmodem.cpp   | 31 +++++++++++++++++++++++++++++++
 5 files changed, 93 insertions(+)

diff --git a/src/OSTimer.cpp b/src/OSTimer.cpp
index 21744615f..3c25abdd9 100644
--- a/src/OSTimer.cpp
+++ b/src/OSTimer.cpp
@@ -29,6 +29,16 @@ static void IRAM_ATTR onTimer()
     (*tCallback)(tParam1, tParam2);
 }
 
+/**
+ * Schedules a hardware callback function to be executed after a specified delay.
+ * 
+ * @param callback The function to be executed.
+ * @param param1 The first parameter to be passed to the function.
+ * @param param2 The second parameter to be passed to the function.
+ * @param delayMsec The delay time in milliseconds before the function is executed.
+ * 
+ * @return True if the function was successfully scheduled, false otherwise.
+ */
 bool scheduleHWCallback(PendableFunction callback, void *param1, uint32_t param2, uint32_t delayMsec)
 {
     if (!timer) {
diff --git a/src/Power.cpp b/src/Power.cpp
index a66ed4ec7..dac158e15 100644
--- a/src/Power.cpp
+++ b/src/Power.cpp
@@ -1,3 +1,14 @@
+/**
+ * @file Power.cpp
+ * @brief This file contains the implementation of the Power class, which is responsible for managing power-related functionality of the device.
+ * It includes battery level sensing, power management unit (PMU) control, and power state machine management.
+ * The Power class is used by the main device class to manage power-related functionality.
+ * 
+ * The file also includes implementations of various battery level sensors, such as the AnalogBatteryLevel class, which assumes the battery voltage is attached via a voltage-divider to an analog input.
+ * 
+ * This file is part of the Meshtastic project.
+ * For more information, see: https://meshtastic.org/
+ */
 #include "power.h"
 #include "NodeDB.h"
 #include "PowerFSM.h"
@@ -366,6 +377,11 @@ bool Power::analogInit()
 #endif
 }
 
+/**
+ * Initializes the Power class.
+ * 
+ * @return true if the setup was successful, false otherwise.
+ */
 bool Power::setup()
 {
     bool found = axpChipInit();
diff --git a/src/PowerFSM.cpp b/src/PowerFSM.cpp
index 2d42ef655..988499e14 100644
--- a/src/PowerFSM.cpp
+++ b/src/PowerFSM.cpp
@@ -1,3 +1,12 @@
+/**
+ * @file PowerFSM.cpp
+ * @brief Implements the finite state machine for power management.
+ * 
+ * This file contains the implementation of the finite state machine (FSM) for power management. 
+ * The FSM controls the power states of the device, including SDS (shallow deep sleep), LS (light sleep), 
+ * NB (normal mode), and POWER (powered mode). The FSM also handles transitions between states and 
+ * actions to be taken upon entering or exiting each state.
+ */
 #include "PowerFSM.h"
 #include "GPS.h"
 #include "MeshService.h"
diff --git a/src/memGet.cpp b/src/memGet.cpp
index 9f59d29ff..4799c7e97 100644
--- a/src/memGet.cpp
+++ b/src/memGet.cpp
@@ -1,8 +1,21 @@
+/**
+ * @file memGet.cpp
+ * @brief Implementation of MemGet class that provides functions to get memory information.
+ * 
+ * This file contains the implementation of MemGet class that provides functions to get 
+ * information about free heap, heap size, free psram and psram size. The functions are 
+ * implemented for ESP32 and NRF52 architectures. If the platform does not have heap 
+ * management function implemented, the functions return UINT32_MAX or 0.
+ */
 #include "memGet.h"
 #include "configuration.h"
 
 MemGet memGet;
 
+/**
+ * Returns the amount of free heap memory in bytes.
+ * @return uint32_t The amount of free heap memory in bytes.
+ */
 uint32_t MemGet::getFreeHeap()
 {
 #ifdef ARCH_ESP32
@@ -15,6 +28,10 @@ uint32_t MemGet::getFreeHeap()
 #endif
 }
 
+/**
+ * Returns the size of the heap memory in bytes.
+ * @return uint32_t The size of the heap memory in bytes.
+ */
 uint32_t MemGet::getHeapSize()
 {
 #ifdef ARCH_ESP32
@@ -27,6 +44,11 @@ uint32_t MemGet::getHeapSize()
 #endif
 }
 
+/**
+ * Returns the amount of free psram memory in bytes.
+ *
+ * @return The amount of free psram memory in bytes.
+ */
 uint32_t MemGet::getFreePsram()
 {
 #ifdef ARCH_ESP32
@@ -36,6 +58,11 @@ uint32_t MemGet::getFreePsram()
 #endif
 }
 
+/**
+ * @brief Returns the size of the PSRAM memory.
+ * 
+ * @return uint32_t The size of the PSRAM memory.
+ */
 uint32_t MemGet::getPsramSize()
 {
 #ifdef ARCH_ESP32
diff --git a/src/xmodem.cpp b/src/xmodem.cpp
index e8727c468..3e4a9eb3e 100644
--- a/src/xmodem.cpp
+++ b/src/xmodem.cpp
@@ -1,3 +1,18 @@
+/**
+ * @file xmodem.cpp
+ * @brief Implementation of XMODEM protocol for Meshtastic devices.
+ * 
+ * This file contains the implementation of the XMODEM protocol for Meshtastic devices. It is based on the XMODEM implementation by Georges Menie (www.menie.org) and has been adapted for protobuf encapsulation. 
+ * 
+ * The XMODEM protocol is used for reliable transmission of binary data over a serial connection. This implementation supports both sending and receiving of data.
+ * 
+ * The XModemAdapter class provides the main functionality for the protocol, including CRC calculation, packet handling, and control signal sending. 
+ * 
+ * @copyright Copyright (c) 2001-2019 Georges Menie
+ * @author 
+ * @author 
+ * @date 
+ */
 /***********************************************************************************************************************
  * based on XMODEM implementation by Georges Menie (www.menie.org)
  ***********************************************************************************************************************
@@ -36,6 +51,13 @@ XModemAdapter xModem;
 
 XModemAdapter::XModemAdapter() {}
 
+/**
+ * Calculates the CRC-16 CCITT checksum of the given buffer.
+ * 
+ * @param buffer The buffer to calculate the checksum for.
+ * @param length The length of the buffer.
+ * @return The calculated checksum.
+ */
 unsigned short XModemAdapter::crc16_ccitt(const pb_byte_t *buffer, int length)
 {
     unsigned short crc16 = 0;
@@ -52,6 +74,15 @@ unsigned short XModemAdapter::crc16_ccitt(const pb_byte_t *buffer, int length)
     return crc16;
 }
 
+/**
+ * Calculates the checksum of the given buffer and compares it to the given
+ * expected checksum. Returns 1 if the checksums match, 0 otherwise.
+ *
+ * @param buf The buffer to calculate the checksum of.
+ * @param sz The size of the buffer.
+ * @param tcrc The expected checksum.
+ * @return 1 if the checksums match, 0 otherwise.
+ */
 int XModemAdapter::check(const pb_byte_t *buf, int sz, unsigned short tcrc)
 {
     return crc16_ccitt(buf, sz) == tcrc;