Added file and initBroker comments

rubnium · Jul 6, 2024 · 0ad5913 · 0ad5913
1 parent 79d0942
commit 0ad5913
Show file tree

Hide file tree

Showing 14 changed files with 90 additions and 10 deletions.
diff --git a/library/src/LoboMQ.h b/library/src/LoboMQ.h
@@ -2,9 +2,9 @@
  * @file LoboMQ.h
  * @author Rubén Gómez Villegas
  * 
- * This library is used to create a MQTT Broker using ESP32 and ESP-NOW protocol.
+ * This file contains importations of every part of the LoboMQ library to be
+ * used.
  */
-
 #ifndef LoboMQ_h
 
 #define LoboMQ_h

diff --git a/library/src/LoboMQ/Broker.cpp b/library/src/LoboMQ/Broker.cpp
@@ -1,3 +1,10 @@
+/**
+ * @file Broker.cpp
+ * @author Rubén Gómez Villegas
+ * 
+ * This file contains the necessary logic to deploy a LoboMQ broker.
+ */
+
 #include "LoboMQ/Broker.h"
 #include "LoboMQ/BrokerTopic.h"
 #include "LoboMQ/BrokerSDUtils.h"

diff --git a/library/src/LoboMQ/Broker.h b/library/src/LoboMQ/Broker.h
@@ -2,7 +2,8 @@
  * @file Broker.h
  * @author Rubén Gómez Villegas
  * 
- * This library is used to create a MQTT Broker using ESP32 and ESP-NOW protocol.
+ * This file contains the necessary definitions and declarations to deploy a
+ * LoboMQ broker.
  */
 
 #ifndef BROKER_H
@@ -37,6 +38,25 @@ typedef struct {
 #define BRO_DEFAULT_PERSISTENCE false
 #define BRO_DEFAULT_CS_SD_PIN -1
 
+/**
+ * @brief Initializes the broker.
+ * This function sets up the proper tasks and queues to handle received message
+ * and gives a node the role of broker. This broker redirects published messages
+ * to the subscribers. If persistence is enabled, topics will be restored on
+ * boot and stored in the SD card.
+ * @param whitelist List with the allowed MAC addresses. If is
+ * `BRO_DEFAULT_WHITELIST`, all MAC addresses are allowed.
+ * @param _logger Pointer to the logger object.
+ * @param persistence If is `true`, the broker will save the topics in a SD
+ * card.
+ * @param csSdPin The Chip Select pin of the SD card module.
+ * @retval `LMQ_ERR_SUCCESS` if the broker is successfully deployed.  
+ * @retval `LMQ_ERR_BAD_ESP_CONFIG` if ESP-NOW couldn't be initialized.
+ * @retval `LMQ_ERR_XQUEUECREATE_FAIL` if the message queues for the tasks
+ * couldn't be created.
+ * @retval `LMQ_ERR_XTASKCREATE_FAIL` if the tasks to process the messages
+ * couldn't be created.
+ */
 LMQErrType initBroker(MACAddrList *whitelist = BRO_DEFAULT_WHITELIST, Elog *_logger = BRO_DEFAULT_LOGGER,
 	bool persistence = BRO_DEFAULT_PERSISTENCE, int csSdPin = BRO_DEFAULT_CS_SD_PIN);
 

diff --git a/library/src/LoboMQ/BrokerSDUtils.cpp b/library/src/LoboMQ/BrokerSDUtils.cpp
@@ -1,3 +1,11 @@
+/**
+ * @file BrokerSDUtils.cpp
+ * @author Rubén Gómez Villegas
+ * 
+ * This file contains the necessary logic to manage `BrokerTopic` objects on the
+ * SD card for LoboMQ.
+ */
+
 #include "LoboMQ/BrokerSDUtils.h"
 
 String replaceChars(const char *str) {

diff --git a/library/src/LoboMQ/BrokerSDUtils.h b/library/src/LoboMQ/BrokerSDUtils.h
@@ -1,3 +1,11 @@
+/**
+ * @file BrokerSDUtils.h
+ * @author Rubén Gómez Villegas
+ * 
+ * This file contains the necessary definitions and declarations to manage
+ * `BrokerTopic` objects on the SD card for LoboMQ.
+ */
+
 #ifndef BROKERSDUTILS_H
 
 #define BROKERSDUTILS_H

diff --git a/library/src/LoboMQ/BrokerTopic.cpp b/library/src/LoboMQ/BrokerTopic.cpp
@@ -1,3 +1,11 @@
+/**
+ * @file BrokerTopic.cpp
+ * @author Rubén Gómez Villegas
+ * 
+ * This file contains the necessary logic to manage objects that represent a
+ * topic in the LoboMQ broker.
+ */
+
 #include "LoboMQ/BrokerTopic.h"
 
 bool hasWildcardCheck(const char topic[]) {

diff --git a/library/src/LoboMQ/BrokerTopic.h b/library/src/LoboMQ/BrokerTopic.h
@@ -2,7 +2,8 @@
  * @file BrokerTopic.h
  * @author Rubén Gómez Villegas
  * 
- * This library is used to create a MQTT Broker using ESP32 and ESP-NOW protocol.
+ * This file contains the necessary definitions and declarations to manage
+ * objects that represent a topic in the LoboMQ broker.
  */
 
 #ifndef BROKERTOPIC_H

diff --git a/library/src/LoboMQ/MACAddrList.cpp b/library/src/LoboMQ/MACAddrList.cpp
@@ -1,3 +1,11 @@
+/**
+ * @file MACAddrList.cpp
+ * @author Rubén Gómez Villegas
+ * 
+ * This file contains the necessary logic to easily manage a vector with MAC
+ * addresses.
+ */
+
 #include "LoboMQ/MACAddrList.h"
 
 bool MACAddrList::isInList(const uint8_t *mac) const {

diff --git a/library/src/LoboMQ/MACAddrList.h b/library/src/LoboMQ/MACAddrList.h
@@ -2,7 +2,8 @@
  * @file MACAddrList.h
  * @author Rubén Gómez Villegas
  * 
- * This library is used to create a MQTT Broker using ESP32 and ESP-NOW protocol.
+ * This file contains the necessary definitions and declarations to easily
+ * manage a vector with MAC addresses.
  */
 
 #ifndef MACADDRLIST_H

diff --git a/library/src/LoboMQ/PubSub.cpp b/library/src/LoboMQ/PubSub.cpp
@@ -1,3 +1,11 @@
+/**
+ * @file PubSub.cpp
+ * @author Rubén Gómez Villegas
+ * 
+ * This file contains the necessary logic to publish, subscribe and unsubscribe
+ * as a LoboMQ client.
+ */
+
 #include "LoboMQ/PubSub.h"
 
 Elog *logger;

diff --git a/library/src/LoboMQ/PubSub.h b/library/src/LoboMQ/PubSub.h
@@ -2,7 +2,8 @@
  * @file PubSub.h
  * @author Rubén Gómez Villegas
  * 
- * This library is used to create a MQTT Broker using ESP32 and ESP-NOW protocol.
+ * This file contains the necessary definitions and declarations to publish,
+ * subscribe and unsubscribe as a LoboMQ client.
  */
 
 #ifndef PUBSUB_H
@@ -66,7 +67,6 @@ typedef struct : public MessageBase {
 	void* content[16];					/**< Any content stored as bytes. */
 } PublishContent;
 
-
 /**
  * @brief Publishes a message to the broker.
  * This function takes the payload and builds a message that will be published

diff --git a/library/src/LoboMQ/commons/Includes.h b/library/src/LoboMQ/commons/Includes.h
@@ -2,7 +2,8 @@
  * @file Includes.h
  * @author Rubén Gómez Villegas
  * 
- * This library is used to create a MQTT Broker using ESP32 and ESP-NOW protocol.
+ * This file contains the definitions and dependencies shared by every LoboMQ
+ * library part.
  */
 
 #ifndef INCLUDES_H

diff --git a/library/src/LoboMQ/commons/Logger.cpp b/library/src/LoboMQ/commons/Logger.cpp
@@ -1,3 +1,11 @@
+/**
+ * @file Logger.cpp
+ * @author Rubén Gómez Villegas
+ * 
+ * This file contains the necessary logic to easily create an Elog logger object
+ * for LoboMQ.
+ */
+
 #include "Logger.h"
 
 SPIClass spi = SPIClass(VSPI);

diff --git a/library/src/LoboMQ/commons/Logger.h b/library/src/LoboMQ/commons/Logger.h
@@ -2,7 +2,8 @@
  * @file Logger.h
  * @author Rubén Gómez Villegas
  * 
- * This library is used to create a MQTT Broker using ESP32 and ESP-NOW protocol.
+ * This file contains the necessary definitions and declarations to easily
+ * create an Elog logger object for LoboMQ.
  */
 
 #ifndef LOGGER_H
@@ -59,7 +60,8 @@ Elog *initializeSerialLogger(LoggerClass className, Loglevel level = DEFAULT_LOG
  * interest.
  * @return A pointer to an Elog instance set up to log to the SD card.
  */
-Elog *initializeSDLogger(LoggerClass className, int cs, int sck, int miso, int mosi, Loglevel level = DEFAULT_LOG_LEVEL);
+Elog *initializeSDLogger(LoggerClass className, int cs, int sck, int miso, int mosi,
+	Loglevel level = DEFAULT_LOG_LEVEL);
 
 /**
  * @brief Creates a logger without the ability to print messages.