From 8eaa4f5627d2ad1722395c1d0f56a3e9c7e4ea51 Mon Sep 17 00:00:00 2001
From: jgromes <jan.gromes@gmail.com>
Date: Fri, 24 May 2019 18:49:26 +0200
Subject: [PATCH] [MQTT] Added Doxygen comments

---
 src/protocols/MQTT.h | 95 +++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 90 insertions(+), 5 deletions(-)

diff --git a/src/protocols/MQTT.h b/src/protocols/MQTT.h
index 696ec34b..d2710047 100644
--- a/src/protocols/MQTT.h
+++ b/src/protocols/MQTT.h
@@ -27,27 +27,112 @@
 #define MQTT_CONNECT_WILL_FLAG                        0b00000100
 #define MQTT_CONNECT_CLEAN_SESSION                    0b00000010
 
+/*!
+  \class MQTTClient
+
+  \brief Client for simple MQTT communication.
+*/
 class MQTTClient {
   public:
-    // constructor
+    /*!
+      \brief Default constructor.
+
+      \param tl Pointer to the wireless module providing TransportLayer communication.
+    */
     MQTTClient(TransportLayer* tl, uint16_t port = 1883);
-    
+
     // basic methods
+
+    /*!
+      \brief Connects to MQTT broker (/server).
+
+      \param host URL of the MQTT broker.
+
+      \param clientId ID of the client.
+
+      \param username Username to be used in the connection. Defaults to empty string (no username).
+
+      \param password Password to be used in the connection. Defaults to empty string (no password).
+
+      \param keepAlive Connection keep-alive period in seconds. Defaults to 60.
+
+      \param cleanSession MQTT CleanSession flag. Defaults to true.
+
+      \param willTopic MQTT will topic. Defaults to empty string (no will topic).
+
+      \param willMessage MQTT will message. Defaults to empty string (no will message).
+
+      \returns \ref status_codes
+    */
     int16_t connect(const char* host, const char* clientId, const char* userName = "", const char* password = "", uint16_t keepAlive = 60, bool cleanSession = true, const char* willTopic = "", const char* willMessage = "");
+
+    /*!
+      \brief Disconnect from MQTT broker.
+
+      \returns \ref status_codes
+    */
     int16_t disconnect();
+
+    /*!
+      \brief Publish MQTT message.
+
+      \param topic MQTT topic to which the message will be published.
+
+      \param message Message to be published.
+
+      \returns \ref status_codes
+    */
     int16_t publish(String& topic, String& message);
+
+    /*!
+      \brief Publish MQTT message.
+
+      \param topic MQTT topic to which the message will be published.
+
+      \param message Message to be published.
+
+      \returns \ref status_codes
+    */
     int16_t publish(const char* topic, const char* message);
+
+    /*!
+      \brief Subscribe to MQTT topic.
+
+      \param topicFilter Topic to subscribe to.
+
+      \returns \ref status_codes
+    */
     int16_t subscribe(const char* topicFilter);
+
+    /*!
+      \brief Unsubscribe from MQTT topic.
+
+      \param topicFilter Topic to unsubscribe from.
+
+      \returns \ref status_codes
+    */
     int16_t unsubscribe(const char* topicFilter);
+
+    /*!
+      \brief Ping MQTT broker. This method can be used to keep connection open.
+
+      \returns \ref status_codes
+    */
     int16_t ping();
+
+    /*!
+      \brief Set function to be called when checking new messages in subscribed topics.
+
+      \returns \ref status_codes
+    */
     int16_t check(void (*func)(const char*, const char*));
-    
+
   private:
     TransportLayer* _tl;
-    
+
     uint16_t _port;
     uint16_t _packetId;
-    
+
     size_t encodeLength(uint32_t len, uint8_t* encoded);
     uint32_t decodeLength(uint8_t* encoded);
 };