Add documentation to a few areas

.vscode/extensions.json

@@ -2,8 +2,9 @@
     // See http://go.microsoft.com/fwlink/?LinkId=827846
     // for the documentation about the extensions.json format
     "recommendations": [
-        "ms-vscode.cpptools",
-        "platformio.platformio-ide",
-        "trunk.io"
+        "platformio.platformio-ide"
     ],
+    "unwantedRecommendations": [
+        "ms-vscode.cpptools-extension-pack"
+    ]
 }

src/FSCommon.cpp

@@ -1,3 +1,11 @@
+/**
+ * @file FSCommon.cpp
+ * @brief This file contains functions for common filesystem operations such as copying, renaming, listing and deleting files and directories.
+ * 
+ * The functions in this file are used to perform common filesystem operations such as copying, renaming, listing and deleting files and directories.
+ * These functions are used in the Meshtastic-device project to manage files and directories on the device's filesystem.
+ * 
+ */
 #include "FSCommon.h"
 #include "configuration.h"
 
@@ -14,6 +22,13 @@ SPIClass SPI1(HSPI);
 
 #endif // HAS_SDCARD
 
+/**
+ * @brief Copies a file from one location to another.
+ * 
+ * @param from The path of the source file.
+ * @param to The path of the destination file.
+ * @return true if the file was successfully copied, false otherwise.
+ */
 bool copyFile(const char *from, const char *to)
 {
 #ifdef FSCom
@@ -43,6 +58,14 @@ bool copyFile(const char *from, const char *to)
 #endif
 }
 
+/**
+ * Renames a file from pathFrom to pathTo.
+ * 
+ * @param pathFrom The original path of the file.
+ * @param pathTo The new path of the file.
+ * 
+ * @return True if the file was successfully renamed, false otherwise.
+ */
 bool renameFile(const char *pathFrom, const char *pathTo)
 {
 #ifdef FSCom
@@ -59,6 +82,13 @@ bool renameFile(const char *pathFrom, const char *pathTo)
 #endif
 }
 
+/**
+ * Lists the contents of a directory.
+ *
+ * @param dirname The name of the directory to list.
+ * @param levels The number of levels of subdirectories to list.
+ * @param del Whether or not to delete the contents of the directory after listing.
+ */
 void listDir(const char *dirname, uint8_t levels, bool del = false)
 {
 #ifdef FSCom
@@ -154,6 +184,13 @@ void listDir(const char *dirname, uint8_t levels, bool del = false)
 #endif
 }
 
+/**
+ * @brief Removes a directory and all its contents.
+ * 
+ * This function recursively removes a directory and all its contents, including subdirectories and files.
+ * 
+ * @param dirname The name of the directory to remove.
+ */
 void rmDir(const char *dirname)
 {
 #ifdef FSCom
@@ -182,6 +219,9 @@ void fsInit()
 #endif
 }
 
+/**
+ * Initializes the SD card and mounts the file system.
+ */
 void setupSDCard()
 {
 #ifdef HAS_SDCARD

src/gps/RTC.cpp

@@ -17,6 +17,10 @@ static uint32_t
     timeStartMsec; // Once we have a GPS lock, this is where we hold the initial msec clock that corresponds to that time
 static uint64_t zeroOffsetSecs; // GPS based time in secs since 1970 - only updated once on initial lock
 
+/**
+ * Reads the current date and time from the RTC module and updates the system time.
+ * @return True if the RTC was successfully read and the system time was updated, false otherwise.
+ */
 void readFromRTC()
 {
     struct timeval tv; /* btw settimeofday() is helpful here too*/
@@ -83,7 +87,15 @@ void readFromRTC()
 #endif
 }
 
-/// If we haven't yet set our RTC this boot, set it from a GPS derived time
+/**
+ * Sets the RTC (Real-Time Clock) if the provided time is of higher quality than the current RTC time.
+ * 
+ * @param q The quality of the provided time.
+ * @param tv A pointer to a timeval struct containing the time to potentially set the RTC to.
+ * @return True if the RTC was set, false otherwise.
+ * 
+ * If we haven't yet set our RTC this boot, set it from a GPS derived time
+ */
 bool perhapsSetRTC(RTCQuality q, const struct timeval *tv)
 {
     static uint32_t lastSetMsec = 0;
@@ -151,6 +163,13 @@ bool perhapsSetRTC(RTCQuality q, const struct timeval *tv)
     }
 }
 
+/**
+ * Sets the RTC time if the provided time is of higher quality than the current RTC time.
+ * 
+ * @param q The quality of the provided time.
+ * @param t The time to potentially set the RTC to.
+ * @return True if the RTC was set to the provided time, false otherwise.
+ */
 bool perhapsSetRTC(RTCQuality q, struct tm &t)
 {
     /* Convert to unix time
@@ -171,11 +190,22 @@ bool perhapsSetRTC(RTCQuality q, struct tm &t)
     }
 }
 
+/**
+ * Returns the current time in seconds since the Unix epoch (January 1, 1970).
+ *
+ * @return The current time in seconds since the Unix epoch.
+ */
 uint32_t getTime()
 {
     return (((uint32_t)millis() - timeStartMsec) / 1000) + zeroOffsetSecs;
 }
 
+/**
+ * Returns the current time from the RTC if the quality of the time is at least minQuality.
+ *
+ * @param minQuality The minimum quality of the RTC time required for it to be considered valid.
+ * @return The current time from the RTC if it meets the minimum quality requirement, or 0 if the time is not valid.
+ */
 uint32_t getValidTime(RTCQuality minQuality)
 {
     return (currentQuality >= minQuality) ? getTime() : 0;

src/modules/ExternalNotificationModule.cpp

@@ -1,3 +1,17 @@
+/**
+ * @file ExternalNotificationModule.cpp
+ * @brief Implementation of the ExternalNotificationModule class.
+ * 
+ * This file contains the implementation of the ExternalNotificationModule class, which is responsible for handling external notifications such as vibration, buzzer, and LED lights.
+ * The class provides methods to turn on and off the external notification outputs and to play ringtones using PWM buzzer.
+ * It also includes default configurations and a runOnce() method to handle the module's behavior.
+ * 
+ * Documentation:
+ * https://meshtastic.org/docs/settings/moduleconfig/external-notification
+ * 
+ * @author Jm Casler & Meshtastic Team
+ * @date [Insert Date]
+ */
 #include "ExternalNotificationModule.h"
 #include "MeshService.h"
 #include "NodeDB.h"
@@ -113,6 +127,11 @@ int32_t ExternalNotificationModule::runOnce()
     }
 }
 
+/**
+ * Sets the external notification on for the specified index.
+ *
+ * @param index The index of the external notification to turn on.
+ */
 void ExternalNotificationModule::setExternalOn(uint8_t index)
 {
     externalCurrentState[index] = 1;

src/modules/RangeTestModule.cpp

@@ -1,3 +1,13 @@
+/**
+ * @file RangeTestModule.cpp
+ * @brief Implementation of the RangeTestModule class and RangeTestModuleRadio class.
+ * 
+ * As a sender, this module sends packets every n seconds with an incremented PacketID.
+ * As a receiver, this module receives packets from multiple senders and saves them to the Filesystem.
+ * 
+ * The RangeTestModule class is an OSThread that runs the module.
+ * The RangeTestModuleRadio class handles sending and receiving packets.
+ */
 #include "RangeTestModule.h"
 #include "FSCommon.h"
 #include "MeshService.h"
@@ -10,11 +20,6 @@
 #include "gps/GeoCoord.h"
 #include <Arduino.h>
 
-/*
-    As a sender, I can send packets every n seconds. These packets include an incremented PacketID.
-    As a receiver, I can receive packets from multiple senders. These packets can be saved to the Filesystem.
-*/
-
 RangeTestModule *rangeTestModule;
 RangeTestModuleRadio *rangeTestModuleRadio;
 
@@ -97,6 +102,12 @@ int32_t RangeTestModule::runOnce()
     return disable();
 }
 
+/**
+ * Sends a payload to a specified destination node.
+ * 
+ * @param dest The destination node number.
+ * @param wantReplies Whether or not to request replies from the destination node.
+ */
 void RangeTestModuleRadio::sendPayload(NodeNum dest, bool wantReplies)
 {
     meshtastic_MeshPacket *p = allocDataPacket();

src/modules/SerialModule.cpp

@@ -86,7 +86,13 @@ SerialModuleRadio::SerialModuleRadio() : MeshModule("SerialModuleRadio")
     }
 }
 
-// For the serial2 port we can't really detect if any client is on the other side, so instead just look for recent messages
+/**
+ * @brief Checks if the serial connection is established.
+ * 
+ * @return true if the serial connection is established, false otherwise.
+ * 
+ * For the serial2 port we can't really detect if any client is on the other side, so instead just look for recent messages
+ */
 bool SerialModule::checkIsConnected()
 {
     uint32_t now = millis();
@@ -191,6 +197,11 @@ int32_t SerialModule::runOnce()
     }
 }
 
+/**
+ * Allocates a new mesh packet for use as a reply to a received packet.
+ * 
+ * @return A pointer to the newly allocated mesh packet.
+ */
 meshtastic_MeshPacket *SerialModuleRadio::allocReply()
 {
     auto reply = allocDataPacket(); // Allocate a packet for sending
@@ -198,6 +209,12 @@ meshtastic_MeshPacket *SerialModuleRadio::allocReply()
     return reply;
 }
 
+/**
+ * Sends a payload to a specified destination node.
+ * 
+ * @param dest The destination node number.
+ * @param wantReplies Whether or not to request replies from the destination node.
+ */
 void SerialModuleRadio::sendPayload(NodeNum dest, bool wantReplies)
 {
     meshtastic_Channel *ch = (boundChannel != NULL) ? &channels.getByName(boundChannel) : NULL;
@@ -216,6 +233,12 @@ void SerialModuleRadio::sendPayload(NodeNum dest, bool wantReplies)
     service.sendToMesh(p);
 }
 
+/**
+ * Handle a received mesh packet.
+ *
+ * @param mp The received mesh packet.
+ * @return The processed message.
+ */
 ProcessMessage SerialModuleRadio::handleReceived(const meshtastic_MeshPacket &mp)
 {
     if (moduleConfig.serial.enabled) {
@@ -277,6 +300,11 @@ ProcessMessage SerialModuleRadio::handleReceived(const meshtastic_MeshPacket &mp
     return ProcessMessage::CONTINUE; // Let others look at this message also if they want
 }
 
+/**
+ * @brief Returns the baud rate of the serial module from the module configuration.
+ * 
+ * @return uint32_t The baud rate of the serial module.
+ */
 uint32_t SerialModule::getBaudRate()
 {
     if (moduleConfig.serial.baud == meshtastic_ModuleConfig_SerialConfig_Serial_Baud_BAUD_110) {

src/modules/esp32/StoreForwardModule.cpp

@@ -1,3 +1,16 @@
+/**
+ * @file StoreForwardModule.cpp
+ * @brief Implementation of the StoreForwardModule class.
+ * 
+ * This file contains the implementation of the StoreForwardModule class, which is responsible for managing the store and forward functionality of the Meshtastic device.
+ * The class provides methods for sending and receiving messages, as well as managing the message history queue.
+ * It also initializes and manages the data structures used for storing the message history.
+ * 
+ * The StoreForwardModule class is used by the MeshService class to provide store and forward functionality to the Meshtastic device.
+ * 
+ * @author Jm Casler
+ * @date [Insert Date]
+ */
 #include "StoreForwardModule.h"
 #include "MeshService.h"
 #include "NodeDB.h"
@@ -52,9 +65,9 @@ int32_t StoreForwardModule::runOnce()
     return disable();
 }
 
-/*
-    Create our data structure in the PSRAM.
-*/
+/**
+ * Populates the PSRAM with data to be sent later when a device is out of range.
+ */
 void StoreForwardModule::populatePSRAM()
 {
     /*
@@ -82,6 +95,12 @@ void StoreForwardModule::populatePSRAM()
     LOG_DEBUG("*** numberOfPackets for packetHistory - %u\n", numberOfPackets);
 }
 
+/**
+ * Sends messages from the message history to the specified recipient.
+ * 
+ * @param msAgo The number of milliseconds ago from which to start sending messages.
+ * @param to The recipient ID to send the messages to.
+ */
 void StoreForwardModule::historySend(uint32_t msAgo, uint32_t to)
 {
     uint32_t queueSize = storeForwardModule->historyQueueCreate(msAgo, to);
@@ -101,6 +120,13 @@ void StoreForwardModule::historySend(uint32_t msAgo, uint32_t to)
     storeForwardModule->sendMessage(to, sf);
 }
 
+/**
+ * Creates a new history queue with messages that were received within the specified time frame.
+ * 
+ * @param msAgo The number of milliseconds ago to start the history queue.
+ * @param to The maximum number of messages to include in the history queue.
+ * @return The ID of the newly created history queue.
+ */
 uint32_t StoreForwardModule::historyQueueCreate(uint32_t msAgo, uint32_t to)
 {
 
@@ -141,6 +167,11 @@ uint32_t StoreForwardModule::historyQueueCreate(uint32_t msAgo, uint32_t to)
     return this->packetHistoryTXQueue_size;
 }
 
+/**
+ * Adds a mesh packet to the history buffer for store-and-forward functionality.
+ *
+ * @param mp The mesh packet to add to the history buffer.
+ */
 void StoreForwardModule::historyAdd(const meshtastic_MeshPacket &mp)
 {
     const auto &p = mp.decoded;
@@ -162,6 +193,12 @@ meshtastic_MeshPacket *StoreForwardModule::allocReply()
     return reply;
 }
 
+/**
+ * Sends a payload to a specified destination node using the store and forward mechanism.
+ * 
+ * @param dest The destination node number.
+ * @param packetHistory_index The index of the packet in the packet history buffer.
+ */
 void StoreForwardModule::sendPayload(NodeNum dest, uint32_t packetHistory_index)
 {
     LOG_INFO("*** Sending S&F Payload\n");
@@ -183,6 +220,12 @@ void StoreForwardModule::sendPayload(NodeNum dest, uint32_t packetHistory_index)
     service.sendToMesh(p);
 }
 
+/**
+ * Sends a message to a specified destination node using the store and forward protocol.
+ * 
+ * @param dest The destination node number.
+ * @param payload The message payload to be sent.
+ */
 void StoreForwardModule::sendMessage(NodeNum dest, meshtastic_StoreAndForward &payload)
 {
     meshtastic_MeshPacket *p = allocDataProtobuf(payload);
@@ -203,6 +246,12 @@ void StoreForwardModule::sendMessage(NodeNum dest, meshtastic_StoreAndForward &p
     service.sendToMesh(p);
 }
 
+/**
+ * Sends a store-and-forward message to the specified destination node.
+ * 
+ * @param dest The destination node number.
+ * @param rr The store-and-forward request/response message to send.
+ */
 void StoreForwardModule::sendMessage(NodeNum dest, meshtastic_StoreAndForward_RequestResponse rr)
 {
     // Craft an empty response, save some bytes in flash
@@ -211,6 +260,11 @@ void StoreForwardModule::sendMessage(NodeNum dest, meshtastic_StoreAndForward_Re
     storeForwardModule->sendMessage(dest, sf);
 }
 
+/**
+ * Sends statistics about the store and forward module to the specified node.
+ *
+ * @param to The node ID to send the statistics to.
+ */
 void StoreForwardModule::statsSend(uint32_t to)
 {
     meshtastic_StoreAndForward sf = meshtastic_StoreAndForward_init_zero;
@@ -231,6 +285,12 @@ void StoreForwardModule::statsSend(uint32_t to)
     storeForwardModule->sendMessage(to, sf);
 }
 
+/**
+ * Handles a received mesh packet, potentially storing it for later forwarding.
+ *
+ * @param mp The received mesh packet.
+ * @return A `ProcessMessage` indicating whether the packet was successfully handled.
+ */
 ProcessMessage StoreForwardModule::handleReceived(const meshtastic_MeshPacket &mp)
 {
 #ifdef ARCH_ESP32
@@ -287,6 +347,13 @@ ProcessMessage StoreForwardModule::handleReceived(const meshtastic_MeshPacket &m
     return ProcessMessage::CONTINUE; // Let others look at this message also if they want
 }
 
+/**
+ * Handles a received protobuf message for the Store and Forward module.
+ * 
+ * @param mp The received MeshPacket to handle.
+ * @param p A pointer to the StoreAndForward object.
+ * @return True if the message was successfully handled, false otherwise.
+ */
 bool StoreForwardModule::handleReceivedProtobuf(const meshtastic_MeshPacket &mp, meshtastic_StoreAndForward *p)
 {
     if (!moduleConfig.store_forward.enabled) {