Merge PR #10: Initial attempt to start documenting things

.gitignore

@@ -1,2 +1,3 @@
 *.user
 .crossbuilder
+docs/nymea-mqtt-html/

docs/config.qdocconf

@@ -0,0 +1,33 @@
+project = nymea-mqtt
+description = nymea-mqtt documentation
+
+dita.metadata.default.author      = Michael Zanetti
+dita.metadata.default.permissions = all
+dita.metadata.default.publisher   = nymea GmbH
+dita.metadata.default.copyryear = 2020
+dita.metadata.default.copyrholder = Michael Zanetti
+dita.metadata.default.audience = programmer
+
+outputdir = nymea-mqtt-html
+outputformats = HTML
+
+language = Cpp
+
+naturallanguage         = en_US
+outputencoding          = UTF-8
+sourceencoding          = UTF-8
+
+#syntaxhighlighting = true
+
+headerdirs = ../libnymea-mqtt
+sourcedirs = ./ ../libnymea-mqtt
+
+headers.fileextensions = "*.h"
+sources.fileextensions = "*.cpp *.qdoc"
+
+Cpp.ignoredirectives = Q_DECLARE_METATYPE \
+                       Q_LOGGING_CATEGORY \
+                       Q_DECLARE_LOGGING_CATEGORY \
+                       Q_ENUM \
+
+

docs/index.qdoc

@@ -0,0 +1,8 @@
+/*!
+    \page index.html
+    \title nymea-mqtt documentation
+
+    \chapter Classes
+    \annotatedlist mqtt
+
+*/

libnymea-mqtt/mqttclient.cpp

@@ -25,6 +25,15 @@
 *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
+/*!
+       \class MqttClient
+       \brief A MQTT client
+       \inmodule nymea-mqtt
+       \ingroup mqtt
+
+       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 +98,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 +113,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,17 @@
 *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
+/*!
+       \class MqttPacket
+       \brief Defines a MQTT packet and serialzes/deserializes to/from network payload.
+       \inmodule nymea-mqtt
+       \ingroup mqtt
+
+       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,40 @@
 *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
+/*!
+       \class MqttServer
+       \brief A MQTT server implementation
+       \inmodule nymea-mqtt
+       \ingroup mqtt
+
+       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
+       \inmodule nymea-mqtt
+       \ingroup mqtt
+
+       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,15 @@
 *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
+/*!
+       \class MqttSubscription
+       \brief A helper class for managing MQTT subscription filters
+       \inmodule nymea-mqtt
+       \ingroup mqtt
+
+       Bundles topic filter and QoS type into a single data type.
+*/
+
 #include "mqttsubscription.h"
 
 MqttSubscription::MqttSubscription()