Initial attempt to start documenting things

libnymea-mqtt/mqttclient.cpp

@@ -25,6 +25,13 @@
 *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
+/*!
+       \class MqttClient
+       \brief A MQTT client
+
+       MqttClient is used to connect to MQTT servers/brokers. The currently supported
+       MQTT protocol version is 3.1.1 including SSL encryption support.
+*/
 #include "mqttclient.h"
 #include "mqttclient_p.h"
 #include "mqttpacket.h"
@@ -89,6 +96,13 @@ void MqttClientPrivate::disconnectFromHost()
     socket->disconnectFromHost();
 }
 
+/*!
+ * \brief Constructs a new MQTT client object.
+ * \param clientId The client ID.
+ * \param parent A QObject parent for this MqttClient.
+ *
+ * The clientId is usually obtained with the credentials for a server.
+ */
 MqttClient::MqttClient(const QString &clientId, QObject *parent):
     QObject(parent),
     d_ptr(new MqttClientPrivate(this))
@@ -97,6 +111,19 @@ MqttClient::MqttClient(const QString &clientId, QObject *parent):
 
 }
 
+/*!
+ * \brief Constructs a new MQTT client object.
+ * \param clientId The client ID.
+ * \param keepAlive The keep alive timeout in seconds
+ * \param willTopic The will topic for this connection
+ * \param willMessage The will message payload for this connection
+ * \param willQoS The QoS used to send the will for this message
+ * \param willRetain Determines whether the will message should be retained on the server
+ * \param parent A QObject parent for this MqttClient.
+ *
+ * The clientId is usually obtained with the credentials for a server. Please refer to the MQTT documentation
+ * for information about how the will message in MQTT works.
+ */
 MqttClient::MqttClient(const QString &clientId, quint16 keepAlive, const QString &willTopic, const QByteArray &willMessage, Mqtt::QoS willQoS, bool willRetain, QObject *parent):
     QObject(parent),
     d_ptr(new MqttClientPrivate(this))

libnymea-mqtt/mqttpacket.cpp

@@ -25,6 +25,15 @@
 *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
+/*!
+       \class MqttPacket
+       \brief Defines a MQTT packet and serialzes/deserializes to/from network payload.
+
+       MqttPacket is used to create MQTT packets to be sent over the network or parse packet
+       payload incoming from the network.
+       The supported MQTT protocol version is 3.1.1.
+*/
+
 #include "mqttpacket.h"
 #include "mqttpacket_p.h"
 

libnymea-mqtt/mqttserver.cpp

@@ -25,6 +25,36 @@
 *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
+/*!
+       \class MqttServer
+       \brief A MQTT server implementation
+
+       MqttServer is used to expose a MQTT server interface in the network. The currently supported
+       MQTT protocol version is 3.1.1 including SSL encryption support.
+       Note: Just starting up such a MqttServer does not provide a full MQTT broker. A MqttServer
+       listens on the network for incoming connections, accepts them and parses the network payload into a
+       MqttPacket.
+
+       A MQTT broker implementation, in addition requires to handle permissions and dispatch MQTT messages
+       between multiple MqttServer interfaces as well as handle will messages across clients.
+
+       When implementing a MQTT broker, reimplement MqttAutorizer. Then instantiate one or many MqttServer objects
+       (depending on the network interfaces to be exposed). Using \l setAutorizer, the custom autorizer is
+       registered at the server and the server will ask back to the autorizer for any incoming connection to
+       be authorized.
+*/
+
+/*!
+       \class MqttAuthorizer
+       \brief Authorizer base class for authorizing incoming client connections on an \l MqttServer
+
+       MqttAuthorizer is the base class for authorization handlers in \l MqttServer interfaces.
+       The \l MqttServer will call the authorizer methods on any incoming connect, publish or subscribe
+       packets. This can be used to check any user/policy database and authorize/reject such requests
+       for particular clients.
+*/
+
+
 #include "mqttserver.h"
 #include "mqttserver_p.h"
 #include "mqttpacket.h"

libnymea-mqtt/mqttsubscription.cpp

@@ -25,6 +25,13 @@
 *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
+/*!
+       \class MqttSubscription
+       \brief A helper class for managing MQTT subscription filters
+
+       Bundles topic filter and QoS type into a single data type.
+*/
+
 #include "mqttsubscription.h"
 
 MqttSubscription::MqttSubscription()