From c6f48d22296806283d0a5cd303887386887d4099 Mon Sep 17 00:00:00 2001 From: Michael Zanetti Date: Tue, 28 May 2019 17:45:30 +0200 Subject: [PATCH 1/4] Initial attempt to start documenting things --- libnymea-mqtt/mqttclient.cpp | 27 +++++++++++++++++++++++++++ libnymea-mqtt/mqttpacket.cpp | 9 +++++++++ libnymea-mqtt/mqttserver.cpp | 30 ++++++++++++++++++++++++++++++ libnymea-mqtt/mqttsubscription.cpp | 7 +++++++ 4 files changed, 73 insertions(+) diff --git a/libnymea-mqtt/mqttclient.cpp b/libnymea-mqtt/mqttclient.cpp index 30a46c6..5f25db3 100644 --- a/libnymea-mqtt/mqttclient.cpp +++ b/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)) diff --git a/libnymea-mqtt/mqttpacket.cpp b/libnymea-mqtt/mqttpacket.cpp index fc3f2e5..d1d4dc7 100644 --- a/libnymea-mqtt/mqttpacket.cpp +++ b/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" diff --git a/libnymea-mqtt/mqttserver.cpp b/libnymea-mqtt/mqttserver.cpp index 854d96b..9f42e05 100644 --- a/libnymea-mqtt/mqttserver.cpp +++ b/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" diff --git a/libnymea-mqtt/mqttsubscription.cpp b/libnymea-mqtt/mqttsubscription.cpp index 24d2aeb..918a964 100644 --- a/libnymea-mqtt/mqttsubscription.cpp +++ b/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() From c826a165b8a363ac3d2ad3fe88b2ba145a2dd640 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20St=C3=BCrz?= Date: Fri, 21 Feb 2020 13:02:50 +0100 Subject: [PATCH 2/4] Add qdoc configuration file for standalone build and create index.html for classes overview --- .gitignore | 1 + docs/config.qdocconf | 33 ++++++++++++++++++++++++++++++ docs/index.qdoc | 8 ++++++++ libnymea-mqtt/mqttclient.cpp | 2 ++ libnymea-mqtt/mqttsubscription.cpp | 2 ++ 5 files changed, 46 insertions(+) create mode 100644 docs/config.qdocconf create mode 100644 docs/index.qdoc diff --git a/.gitignore b/.gitignore index 1cd3ed2..1935770 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ *.user .crossbuilder +docs/nymea-mqtt-raw/ diff --git a/docs/config.qdocconf b/docs/config.qdocconf new file mode 100644 index 0000000..843d985 --- /dev/null +++ b/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-raw +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 \ + + diff --git a/docs/index.qdoc b/docs/index.qdoc new file mode 100644 index 0000000..cfbe01d --- /dev/null +++ b/docs/index.qdoc @@ -0,0 +1,8 @@ +/*! + \page index.html + \title nymea-mqtt documentation + + \chapter Classes + \annotatedlist mqtt + +*/ diff --git a/libnymea-mqtt/mqttclient.cpp b/libnymea-mqtt/mqttclient.cpp index 5f25db3..e164e89 100644 --- a/libnymea-mqtt/mqttclient.cpp +++ b/libnymea-mqtt/mqttclient.cpp @@ -28,6 +28,8 @@ /*! \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. diff --git a/libnymea-mqtt/mqttsubscription.cpp b/libnymea-mqtt/mqttsubscription.cpp index 918a964..cefe9a5 100644 --- a/libnymea-mqtt/mqttsubscription.cpp +++ b/libnymea-mqtt/mqttsubscription.cpp @@ -28,6 +28,8 @@ /*! \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. */ From ab29879f4e49c31162e962af1d74bb2fd83e42f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20St=C3=BCrz?= Date: Fri, 21 Feb 2020 13:10:39 +0100 Subject: [PATCH 3/4] Add inmodule for classes and provide the classes list in the index.qdoc --- docs/config.qdocconf | 2 +- libnymea-mqtt/mqttpacket.cpp | 2 ++ libnymea-mqtt/mqttserver.cpp | 4 ++++ 3 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/config.qdocconf b/docs/config.qdocconf index 843d985..e58cf2b 100644 --- a/docs/config.qdocconf +++ b/docs/config.qdocconf @@ -8,7 +8,7 @@ dita.metadata.default.copyryear = 2020 dita.metadata.default.copyrholder = Michael Zanetti dita.metadata.default.audience = programmer -outputdir = nymea-mqtt-raw +outputdir = nymea-mqtt-html outputformats = HTML language = Cpp diff --git a/libnymea-mqtt/mqttpacket.cpp b/libnymea-mqtt/mqttpacket.cpp index d1d4dc7..db423de 100644 --- a/libnymea-mqtt/mqttpacket.cpp +++ b/libnymea-mqtt/mqttpacket.cpp @@ -28,6 +28,8 @@ /*! \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. diff --git a/libnymea-mqtt/mqttserver.cpp b/libnymea-mqtt/mqttserver.cpp index 9f42e05..72861ed 100644 --- a/libnymea-mqtt/mqttserver.cpp +++ b/libnymea-mqtt/mqttserver.cpp @@ -28,6 +28,8 @@ /*! \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. @@ -47,6 +49,8 @@ /*! \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 From 3e969e951029fb9d759fa20c94addac1584ddef2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20St=C3=BCrz?= Date: Fri, 21 Feb 2020 13:11:45 +0100 Subject: [PATCH 4/4] Update gitignore to the documentation output folder --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 1935770..1316ad4 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,3 @@ *.user .crossbuilder -docs/nymea-mqtt-raw/ +docs/nymea-mqtt-html/