docs(uat): add doxygen documentation to mosquitto client (#392)

uat/custom-components/client-mosquitto-c/.gitignore

@@ -2,3 +2,4 @@
 /mosquitto-test-client.amd64.tar.gz
 /proto/
 /target/
+/docs/

uat/custom-components/client-mosquitto-c/pom.xml

@@ -75,6 +75,7 @@
                             <excludes>
                                 <exclude>*</exclude>
                                 <exclude>build/**</exclude>
+                                <exclude>docs/**</exclude>
                             </excludes>
                         </licenseSet>
                     </licenseSets>

uat/custom-components/client-mosquitto-c/scripts/generate-docs.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+#
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+
+doxygen

uat/custom-components/client-mosquitto-c/src/ClientException.h

@@ -11,15 +11,33 @@
 
 
 /**
- * ClientException class.
+ * ClientException class represent generic exceptions of client.
  */
 class ClientException : public std::exception {
 public:
+
+    /**
+     * Constructor of ClientException.
+     *
+     * @param message the message of exception
+     * @param code the error code
+     */
     ClientException(const char * message, int code = 0)
         : m_message(message), m_code(code) {}
     ~ClientException() {}
 
+    /**
+     * Gets message of the exception.
+     *
+     * @return string with exception's message
+     */
     const std::string & getMessage() const { return m_message; }
+
+    /**
+     * Gets error code of the exception.
+     *
+     * @return integer of error code of the exception
+     */
     int getCode() const { return m_code; }
 
 private:

uat/custom-components/client-mosquitto-c/src/GRPCControlServer.h

@@ -41,35 +41,104 @@ class MqttConnection;
  */
 class GRPCControlServer final : public MqttClientControl::Service {
 public:
+
+    /**
+     * Constructor of GRPCControlServer.
+     *
+     * @param client the reference to client part of bi-directional gRPC link
+     * @param host address to listen
+     * @param port port to listen
+     */
     GRPCControlServer(GRPCDiscoveryClient & client, const char * host, unsigned short port);
 
     /**
      * Get actual bound port.
      */
     unsigned short getPort() const { return m_choosen_port; }
 
+    /**
+     * Gets reason of shutdown received from the control.
+     *
+     * @return reason of shutdown received from the control
+     */
     const std::string & getShutdownReason() const { return m_shutdown_reason; }
+
     /**
      * Handle incoming gRPC requests.
      * @return shutdown reason
      */
     void wait(MqttLib & mqtt);
 
 
+    /**
+     * Break waiting for new requests.
+     */
     void unblockWait() { m_exit_requested.set_value(); }
 
     /**
      * Build gRPC address string from host and port.
      */
     static std::string buildAddress(const char * host, unsigned short port);
 
+    /**
+     * Handles ShutdownAgent gRPC request.
+     *
+     * @param context the gRPC context.
+     * @param request the shutdown gRPC request
+     * @param reply the pointer to reply to fill
+     * @return status of gRPC request
+     */
     Status ShutdownAgent(ServerContext * context, const ShutdownRequest * request, Empty * reply) override;
+
+    /**
+     * Handles CreateMqttConnection gRPC request.
+     *
+     * @param context the gRPC context.
+     * @param request the connect gRPC request
+     * @param reply the pointer to reply to fill
+     * @return status of gRPC request
+     */
     Status CreateMqttConnection(ServerContext * context, const MqttConnectRequest * request, MqttConnectReply * reply) override;
+
+    /**
+     * Handles CloseMqttConnection gRPC request.
+     *
+     * @param context the gRPC context.
+     * @param request the close gRPC request
+     * @param reply the pointer to reply to fill
+     * @return status of gRPC request
+     */
     Status CloseMqttConnection(ServerContext * context, const MqttCloseRequest * request, Empty * reply) override;
+
+    /**
+     * Handles SubscribeMqtt gRPC request.
+     *
+     * @param context the gRPC context.
+     * @param request the subscribe gRPC request
+     * @param reply the pointer to reply to fill
+     * @return status of gRPC request
+     */
     Status SubscribeMqtt(ServerContext * context, const MqttSubscribeRequest * request, MqttSubscribeReply * reply) override;
+
+    /**
+     * Handles UnsubscribeMqtt gRPC request.
+     *
+     * @param context the gRPC context.
+     * @param request the unsubscribe gRPC request
+     * @param reply the pointer to reply to fill
+     * @return status of gRPC request
+     */
     Status UnsubscribeMqtt(ServerContext * context, const MqttUnsubscribeRequest * request, MqttSubscribeReply * reply) override;
-    Status PublishMqtt(ServerContext * context, const MqttPublishRequest * request, MqttPublishReply * reply) override;
 
+    /**
+     * Handles PublishMqtt gRPC request.
+     *
+     * @param context the gRPC context.
+     * @param request the publish gRPC request
+     * @param reply the pointer to reply to fill
+     * @return status of gRPC request
+     */
+    Status PublishMqtt(ServerContext * context, const MqttPublishRequest * request, MqttPublishReply * reply) override;
 
 private:
     std::string getJoinedCA(const TLSSettings & tls_settings);

uat/custom-components/client-mosquitto-c/src/GRPCDiscoveryClient.h

@@ -24,12 +24,36 @@ class Status;
  */
 class GRPCDiscoveryClient {
 public:
+    /**
+     * Constructor of GRPCDiscoveryClient.
+     *
+     * @param agent_id the id of agent
+     * @param channel gRPC communication channel
+     */
     GRPCDiscoveryClient(const std::string & agent_id, std::shared_ptr<Channel> channel)
         : m_agent_id(agent_id), m_stub(MqttAgentDiscovery::NewStub(channel)) {
     }
 
+    /**
+     * Handles RegisterAgent gRPC request.
+     *
+     * @param local_ip the local IP of agent as seen by control
+     */
     bool RegisterAgent(std::string & local_ip);
+
+    /**
+     * Handles DiscoveryAgent gRPC request.
+     *
+     * @param address the address of gRPC server of the control
+     * @param port the port of gRPC server of the control
+     */
     bool DiscoveryAgent(const char * address, unsigned short port);
+
+    /**
+     * Handles UnregisterAgent gRPC request.
+     *
+     * @param reason the reason of unregistration
+     */
     bool UnregisterAgent(const std::string & reason);
 
     /**

uat/custom-components/client-mosquitto-c/src/GRPCException.h

@@ -10,12 +10,18 @@
 
 
 /**
- * MqttException class.
+ * GRPCException class represent gRPC side exceptions.
  */
 class GRPCException : public ClientException {
 public:
+    /**
+     * Constructor of GRPCException.
+     *
+     * @param message the message of exception
+     * @param code the error code
+     */
     GRPCException(const char * message, int code = 0)
-        :ClientException(message, code) {}
+        : ClientException(message, code) {}
     ~GRPCException() {}
 };
 

uat/custom-components/client-mosquitto-c/src/GRPCLib.h

@@ -11,6 +11,11 @@
 
 class GRPCLink;
 
+/**
+ * GRPCLib class.
+ *
+ * Represent gRPC resources on whole process level.
+ */
 class GRPCLib {
 public:
 

uat/custom-components/client-mosquitto-c/src/GRPCLink.h

@@ -13,6 +13,11 @@ class MqttLib;
 class GRPCDiscoveryClient;
 class GRPCControlServer;
 
+/**
+ * GRPCLink class.
+ *
+ * Represent bi-directinal gRPC communication channel with control.
+ */
 class GRPCLink {
 public:
     /**
@@ -28,8 +33,9 @@ class GRPCLink {
 
     /**
      * Handle gRPC requests.
-     * @param MqttLib MQTT library handler
-     * @return shutdown reason
+     *
+     * @param mqtt MQTT library handler
+     * @return the reason of shutdown
      */
     std::string handleRequests(MqttLib & mqtt) const;
 

uat/custom-components/client-mosquitto-c/src/MqttConnection.cpp

@@ -26,21 +26,58 @@
 #define CONNECT_REQUEST_ID              (1024*64 + 1)
 #define DISCONNECT_REQUEST_ID           (1024*64 + 2)
 
+/**
+ * AsyncResult class represent response to asynchronous request.
+ */
 class AsyncResult {
 public:
-    int rc;                                     // all
-    int flags;                                  // connect
-    mosquitto_property * props;                 // all
-    int mid;                                    // subscribe / publish / unsubscribe
-    std::vector<int> granted_qos;               // subscribe
+    /**
+     * Reason code. Used by all requests.
+     */
+    int rc;
 
-    // subscribe
+    /**
+     * Flags. Used only by CONNECT request.
+     */
+    int flags;
+
+    /**
+     * Properties of ACK. Used by all requests.
+     */
+    mosquitto_property * props;
+
+    /**
+     * Message id. Used by SUBSCRIBE PUBLISH and UNSUBSCRIBE requests.
+     */
+    int mid;
+
+    /**
+     * Vector of granted QoS from SUBACK.
+     * Used only for SUBSCRIBE request.
+     */
+    std::vector<int> granted_qos;
+
+    /**
+     * Constructor of AsyncResult used for SUBSCRIBE.
+     *
+     * @param mid_ the message id of broker's response
+     * @param qos_count the count of granted QoS items of SUBACK
+     * @param granted_qos_arr the array of granted QoS items of SUBACK
+     * @param props_ the SUBACK properties
+     */
     AsyncResult(int mid_, int qos_count, const int * granted_qos_arr, const mosquitto_property * props_)
         : rc(MOSQ_ERR_SUCCESS), flags(0), props(NULL), mid(mid_), granted_qos(granted_qos_arr, granted_qos_arr + qos_count) {
         mosquitto_property_copy_all(&props, props_);
     }
 
-    // connect / disconnect / unsubscribe / publish
+    /**
+     * Constructor of AsyncResult used for connect / disconnect / unsubscribe / publish.
+     *
+     * @param rc_ the reason code of CONNACK UNSUBACK or PUBACK
+     * @param props_ the properties of CONNACK UNSUBACK or PUBACK
+     * @param flags_ response flags
+     * @param mid_ the message id of broker's response
+     */
     AsyncResult(int rc_, const mosquitto_property * props_, int flags_ = 0, int mid_ = 0)
         :  rc(rc_), flags(flags_), props(NULL), mid(mid_), granted_qos() {
         mosquitto_property_copy_all(&props, props_);
@@ -49,17 +86,32 @@ class AsyncResult {
     AsyncResult(const AsyncResult &) = delete;
     AsyncResult & operator=(const AsyncResult &) = delete;
 
+    /**
+     * Destructor of AsyncResult.
+     */
     ~AsyncResult() {
         if (props) {
             mosquitto_property_free_all(&props);
         }
     }
 };
 
+
+/**
+ * PendingRequest class represent pending asynchronous request.
+ */
 class PendingRequest {
 public:
+    /**
+     * Constructor of PendingRequest.
+     */
     PendingRequest() : m_valid(true) {}
 
+    /**
+     * Waiting until request completed.
+     *
+     * @param timeout the value in second how many time wait to request completes
+     */
     std::shared_ptr<AsyncResult> waitForResult(unsigned timeout) {
         std::chrono::seconds duration(timeout);
         auto future = m_promise.get_future();
@@ -79,11 +131,22 @@ class PendingRequest {
         }
     }
 
+    /**
+     * Submit result of request.
+     * In addition invalidates request.
+     *
+     * @param result the result of request
+     */
     void submitResult(const std::shared_ptr<AsyncResult> & result) {
         m_promise.set_value(result);
         m_valid = false;
     }
 
+    /**
+     * Check request is valid.
+     *
+     * @return true when request is still valid
+     */
     bool isValid() const {
         return m_valid;
     }

uat/custom-components/client-mosquitto-c/src/MqttConnection.h

@@ -61,6 +61,11 @@ class MqttConnection {
     ~MqttConnection();
 
 
+    /**
+     * Sets connection id.
+     *
+     * @param connection_id the connection id to set
+     */
     void setConnectionId(int connection_id) {
         m_connection_id = connection_id;
     }