Fixed doc comment and deprecation warnings.

examples/async_publish_time.cpp

@@ -130,8 +130,7 @@ int main(int argc, char* argv[])
         auto top = mqtt::topic(cli, "data/time", QOS);
         cout << "Publishing data..." << endl;
 
-        while (timestamp() % DELTA_MS != 0)
+        while (timestamp() % DELTA_MS != 0);
-            ;
 
         uint64_t t = timestamp(), tlast = t, tstart = t;
 

examples/async_subscribe.cpp

@@ -205,8 +205,7 @@ int main(int argc, char* argv[])
 
     // Just block till user tells us to quit.
 
-    while (std::tolower(std::cin.get()) != 'q')
+    while (std::tolower(std::cin.get()) != 'q');
-        ;
 
     // Disconnect
 

examples/sync_consume_v5.cpp

@@ -84,8 +84,7 @@ int main(int argc, char* argv[])
 {
     mqtt::client cli(SERVER_ADDRESS, CLIENT_ID, mqtt::create_options(MQTTVERSION_5));
 
-    auto connOpts = mqtt::connect_options_builder()
+    auto connOpts = mqtt::connect_options_builder::v5()
-                        .mqtt_version(MQTTVERSION_5)
                         .automatic_reconnect(seconds(2), seconds(30))
                         .clean_start(false)
                         .properties({{mqtt::property::SESSION_EXPIRY_INTERVAL, INFINITE}})

include/mqtt/async_client.h

@@ -196,7 +196,6 @@ private:
      * server, which allows for off-line message buffering.
      * This allows the caller to specify a user-defined persistence object,
      * or use no persistence.
-     * @param opts The create options
      * @throw exception if an argument is invalid
      */
     void create();
@@ -223,8 +222,7 @@ public:
      *  				as a URI.
      * @param clientId a client identifier that is unique on the server
      *  			   being connected to
-     * @param persistence The user persistence structure. If this is null,
+     * @param persistence The persistence that the client should use.
-     *  				  then no persistence is used.
      * @throw exception if an argument is invalid
      */
     async_client(
@@ -243,7 +241,7 @@ public:
      *  			   being connected to
      * @param maxBufferedMessages the maximum number of messages allowed to
      *  						  be buffered while not connected
-     * @param persistDir The directory to use for persistence data
+     * @param persistence The persistence that the client should use.
      * @throw exception if an argument is invalid
      */
     async_client(
@@ -262,7 +260,7 @@ public:
      * @param clientId a client identifier that is unique on the server
      *  			   being connected to
      * @param opts The create options
-     * @param persistDir The directory to use for persistence data
+     * @param persistence The persistence that the client should use.
      * @throw exception if an argument is invalid
      */
     async_client(
@@ -582,7 +580,7 @@ public:
      *  			   server.
      * @param userContext optional object used to pass context to the
      *  				  callback. Use @em nullptr if not required.
-     * @param cb
+     * @param cb Listener callback object
      * @return token used to track and wait for the publish to complete. The
      *  	   token will be passed to callback methods if set.
      */
@@ -631,7 +629,7 @@ public:
      * Subscribe to a topic, which may include wildcards.
      * @param topicFilter the topic to subscribe to, which can include
      *  				  wildcards.
-     * @param qos the maximum quality of service at which to subscribe.
+     * @param qos The maximum quality of service at which to subscribe.
      *  		  Messages published at a lower quality of service will be
      *  		  received at the published QoS. Messages published at a
      *  		  higher quality of service will be received using the QoS
@@ -651,8 +649,9 @@ public:
     ) override;
     /**
      * Subscribe to multiple topics, each of which may include wildcards.
-     * @param topicFilters
+     * @param topicFilters The collection of topic filters to subscribe to,
-     * @param qos the maximum quality of service at which to subscribe.
+     *                     any of which can include wildcards
+     * @param qos The maximum quality of service at which to subscribe.
      *  		  Messages published at a lower quality of service will be
      *  		  received at the published QoS. Messages published at a
      *  		  higher quality of service will be received using the QoS
@@ -669,13 +668,14 @@ public:
     ) override;
     /**
      * Subscribes to multiple topics, each of which may include wildcards.
-     * @param topicFilters
+     * @param topicFilters The collection of topic filters to subscribe to,
-     * @param qos the maximum quality of service at which to subscribe.
+     *                     any of which can include wildcards
+     * @param qos The maximum quality of service at which to subscribe.
      *  		  Messages published at a lower quality of service will be
      *  		  received at the published QoS. Messages published at a
      *  		  higher quality of service will be received using the QoS
      *  		  specified on the subscribe.
-     * @param userContext optional object used to pass context to the
+     * @param userContext Optional object used to pass context to the
      *  				  callback. Use @em nullptr if not required.
      * @param cb listener that will be notified when subscribe has completed
      * @param opts The MQTT v5 subscribe options (one for each topic)
@@ -691,17 +691,17 @@ public:
     ) override;
     /**
      * Requests the server unsubscribe the client from a topic.
-     * @param topicFilter the topic to unsubscribe from. It must match a
+     * @param topicFilter The topic to unsubscribe from. It must match a
      *  				  topicFilter specified on an earlier subscribe.
      * @param props The MQTT v5 properties.
-     * @return token used to track and wait for the unsubscribe to complete.
+     * @return token Used to track and wait for the unsubscribe to complete.
      *  	   The token will be passed to callback methods if set.
      */
     token_ptr unsubscribe(const string& topicFilter, const properties& props = properties())
         override;
     /**
      * Requests the server unsubscribe the client from one or more topics.
-     * @param topicFilters one or more topics to unsubscribe from. Each
+     * @param topicFilters One or more topics to unsubscribe from. Each
      *  				   topicFilter must match one specified on an
      *  				   earlier subscribe.
      * @param props The MQTT v5 properties.
@@ -713,7 +713,9 @@ public:
     ) override;
     /**
      * Requests the server unsubscribe the client from one or more topics.
-     * @param topicFilters
+     * @param topicFilters One or more topics to unsubscribe from. Each
+     *  				   topicFilter must match one specified on an
+     *  				   earlier subscribe.
      * @param userContext optional object used to pass context to the
      *  				  callback. Use @em nullptr if not required.
      * @param cb listener that will be notified when unsubscribe has

include/mqtt/client.h

@@ -184,7 +184,7 @@ public:
     virtual connect_response connect();
     /**
      * Connects to an MQTT server using the specified options.
-     * @param opts
+     * @param opts The connect options
      */
     virtual connect_response connect(connect_options opts);
     /**
@@ -327,8 +327,8 @@ public:
     }
     /**
      * Subscribe to a topic, which may include wildcards using a QoS of 1.
-     * @param topicFilter
+     * @param topicFilter A single topic to subscribe
-     * @param props The MQTT v5 properties.
+maked      * @param props The MQTT v5 properties.
      * @param opts The MQTT v5 subscribe options for the topic
      * @return The "subscribe" response from the server.
      */

include/mqtt/connect_options.h

@@ -106,7 +106,7 @@ class connect_options
      * @note In the connect options, by default, the Paho C treats
      * nullptr char arrays as unset values, so we keep that semantic and
      * only set those char arrays if the string is non-empty.
-     * @param str The C++ string object.
+     * @param sr The C++ string object.
      * @return Pointer to a NUL terminated string. This is only valid until
      *  	   the next time the string is updated.
      */
@@ -295,8 +295,8 @@ public:
      */
     const_string_collection_ptr get_servers() const { return serverURIs_; }
     /**
-     * Gets the version of MQTT to be used on the connect.
+     * Gets the version of MQTT to be used for the connection.
-     * @return
+     * @return The version of MQTT to be used for the connection:
      * @li MQTTVERSION_DEFAULT (0) = default: start with 3.1.1, and if that
      *     fails, fall back to 3.1
      * @li MQTTVERSION_3_1 (3) = only try version 3.1
@@ -333,8 +333,8 @@ public:
      * This will only take effect if the version is _already_ set to v3.x
      * (not v5).
      *
-     * @param clean @em true if the server should NOT remember state for the
+     * @param cleanSession @em true if the server should NOT remember state
-     *  			client across reconnects, @em false otherwise.
+     *              for the client across reconnects, @em false otherwise.
      */
     void set_clean_session(bool cleanSession);
     /**
@@ -347,8 +347,8 @@ public:
      *
      * This will only take effect if the MQTT version is set to v5
      *
-     * @param clean @em true if the server should NOT remember state for the
+     * @param cleanStart @em true if the server should NOT remember state
-     *  			client across reconnects, @em false otherwise.
+     *              for the client across reconnects, @em false otherwise.
      */
     void set_clean_start(bool cleanStart);
     /**
@@ -463,7 +463,9 @@ public:
      * call it before setting any other version-specific options. @sa
      * connect_options::v5()
      */
-    void set_mqtt_version(int mqttVersion);
+    [[deprecated("Use a versioned creation function to construct for the desired version"
+    )]] void
+    set_mqtt_version(int mqttVersion);
     /**
      * Enable or disable automatic reconnects.
      * The retry intervals are not affected.
@@ -747,15 +749,16 @@ public:
         return *this;
     }
     /**
-     * Sets the user name to use for the connection.
+     * Sets the user name for the connection.
-     * @param userName
+     * @param userName The user name for the connection.
      */
     auto user_name(string_ref userName) -> self& {
         opts_.set_user_name(userName);
         return *this;
     }
     /**
-     * Sets the password to use for the connection.
+     * Sets the password for the connection.
+     * @param password The password for the connection.
      */
     auto password(binary_ref password) -> self& {
         opts_.set_password(password);
@@ -853,7 +856,9 @@ public:
      * this function, call it before setting any other version-specific
      * options. @sa connect_options_builder::v5()
      */
-    auto mqtt_version(int ver) -> self& {
+    [[deprecated("Use a versioned creation function to construct for the desired version"
+    )]] auto
+    mqtt_version(int ver) -> self& {
         opts_.set_mqtt_version(ver);
         return *this;
     }

include/mqtt/create_options.h

@@ -136,7 +136,7 @@ public:
      *  			   being connected to
      * @param maxBufferedMessages the maximum number of messages allowed to
      *  						  be buffered while not connected
-     * @param persistDir The directory to use for persistence data
+     * @param persistence The persistence that the client should use.
      * @throw exception if an argument is invalid
      */
     create_options(
@@ -155,7 +155,7 @@ public:
      * @param clientId a client identifier that is unique on the server
      *  			   being connected to
      * @param opts The create options
-     * @param persistDir The directory to use for persistence data
+     * @param persistence The persistence that the client should use.
      * @throw exception if an argument is invalid
      */
     create_options(
@@ -199,7 +199,7 @@ public:
     const string& get_server_uri() const noexcept { return serverURI_; };
     /**
      * Set the client identifier.
-     * @param The client identifier.
+     * @param clientId The client identifier.
      */
     void set_client_id(const string& clientId) { clientId_ = clientId; }
     /**

include/mqtt/delivery_token.h

@@ -49,7 +49,7 @@ class delivery_token : public token
 
     /**
      * Sets the message to which this token corresponds.
-     * @param msg
+     * @param msg The message to which this token corresponds.
      */
     void set_message(const_message_ptr msg) { msg_ = msg; }
 

include/mqtt/iaction_listener.h

@@ -60,12 +60,12 @@ public:
     virtual ~iaction_listener() {}
     /**
      * This method is invoked when an action fails.
-     * @param asyncActionToken
+     * @param asyncActionToken The token
      */
     virtual void on_failure(const token& asyncActionToken) = 0;
     /**
      * This method is invoked when an action has completed successfully.
-     * @param asyncActionToken
+     * @param asyncActionToken The token
      */
     virtual void on_success(const token& asyncActionToken) = 0;
 };

include/mqtt/iasync_client.h

@@ -196,11 +196,11 @@ public:
     /**
      * Publishes a message to a topic on the server
      * @param topic The topic to deliver the message to
-     * @param payload the bytes to use as the message payload
+     * @param payload The bytes to use as the message payload
-     * @param n the number of bytes in the payload
+     * @param n The number of bytes in the payload
-     * @param qos the Quality of Service to deliver the message at. Valid
+     * @param qos The Quality of Service to deliver the message at. Valid
      *  		  values are 0, 1 or 2.
-     * @param retained whether or not this message should be retained by the
+     * @param retained Whether or not this message should be retained by the
      *  			   server.
      * @return token used to track and wait for the publish to complete. The
      *  	   token will be passed to callback methods if set.
@@ -220,15 +220,15 @@ public:
     /**
      * Publishes a message to a topic on the server
      * @param topic The topic to deliver the message to
-     * @param payload the bytes to use as the message payload
+     * @param payload The bytes to use as the message payload
-     * @param n the number of bytes in the payload
+     * @param n The number of bytes in the payload
-     * @param qos the Quality of Service to deliver the message at. Valid
+     * @param qos The Quality of Service to deliver the message at. Valid
      *  		  values are 0, 1 or 2.
      * @param retained whether or not this message should be retained by the
      *  			   server.
-     * @param userContext optional object used to pass context to the
+     * @param userContext Optional object used to pass context to the
      *  				  callback. Use @em nullptr if not required.
-     * @param cb
+     * @param cb The listener callback object
      * @return token used to track and wait for the publish to complete. The
      *  	   token will be passed to callback methods if set.
      */

include/mqtt/message.h

@@ -79,7 +79,7 @@ private:
 
     /**
      * Set the dup flag in the underlying message
-     * @param dup
+     * @param dup Whether to set the dup flag.
      */
     void set_duplicate(bool dup) { msg_.dup = to_int(dup); }
 

include/mqtt/properties.h

@@ -224,7 +224,8 @@ inline uint16_t get<uint16_t>(const property& prop) {
  *  		   `get<uint16_t>()`
  */
 template <>
-inline int16_t get<int16_t>(const property& prop) {
+[[deprecated("Integer properties are unsigned. Use get<uint16_t>()")]] inline int16_t
+get<int16_t>(const property& prop) {
     return (int16_t)prop.c_struct().value.integer2;
 }
 
@@ -244,7 +245,8 @@ inline uint32_t get<uint32_t>(const property& prop) {
  *  		   `get<uint32_t>()`
  */
 template <>
-inline int32_t get<int32_t>(const property& prop) {
+[[deprecated("Integer properties are unsigned. Use get<uint32_t>()")]] inline int32_t
+get<int32_t>(const property& prop) {
     return (int32_t)prop.c_struct().value.integer4;
 }
 

include/mqtt/thread_queue.h

@@ -61,8 +61,8 @@ namespace mqtt {
  * shared pointers, as the "dead" part of the queue will not hold onto a
  * reference count after the item has been removed from the queue.
  *
- * @param T The type of the items to be held in the queue.
+ * @tparam T The type of the items to be held in the queue.
- * @param Container The type of the underlying container to use. It must
+ * @tparam Container The type of the underlying container to use. It must
  * support back(), front(), push_back(), pop_front().
  */
 template <typename T, class Container = std::deque<T>>

include/mqtt/topic.h

@@ -6,7 +6,7 @@
 /////////////////////////////////////////////////////////////////////////////
 
 /*******************************************************************************
- * Copyright (c) 2013-2016 Frank Pagliughi <fpagliughi@mindspring.com>
+ * Copyright (c) 2013-2024 Frank Pagliughi <fpagliughi@mindspring.com>
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v2.0
@@ -212,13 +212,13 @@ public:
      */
     explicit topic_filter(const string& filter);
     /**
-     * Determines if the specified topic filter contains any wildcards.
+     * Determines if the specified topic/filter contains any wildcards.
      *
-     * @param filter The topic filter string to check for wildcards.
+     * @param filter The topic/filter string to check for wildcards.
      * @return @em true if any of the fields contain a wildcard, @em false
      *  	   if not.
      */
-    static bool has_wildcards(const string& topic);
+    static bool has_wildcards(const string& filter);
     /**
      * Determines if this topic filter contains any wildcards.
      *

include/mqtt/will_options.h

@@ -86,7 +86,7 @@ private:
      * while others expect NULL pointers for missing parameters.
      * So we always return a pointer to a valid C char array, even when
      * empty.
-     * @param str The C++ string object.
+     * @param sr The C++ string object.
      * @return Pointer to a NUL terminated string. This is only valid until
      *  	   the next time the string is updated. This is never nullptr.
      */

src/properties.cpp

@@ -202,7 +202,7 @@ std::ostream& operator<<(std::ostream& os, const property& prop)
         case MQTTPROPERTY_TYPE_TWO_BYTE_INTEGER:
         case MQTTPROPERTY_TYPE_FOUR_BYTE_INTEGER:
         case MQTTPROPERTY_TYPE_VARIABLE_BYTE_INTEGER:
-            os << get<int>(prop);
+            os << get<uint32_t>(prop);
             break;
 
         case MQTTPROPERTY_TYPE_BINARY_DATA: {

test/unit/test_connect_options.cpp

@@ -255,7 +255,9 @@ TEST_CASE("connect_options move_constructor", "[options]")
         // Check that we got the correct properties
         REQUIRE(1 == opts.get_properties().size());
         REQUIRE(opts.get_properties().contains(property::SESSION_EXPIRY_INTERVAL));
-        REQUIRE(42 == get<int>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL));
+        REQUIRE(
+            42 == get<uint32_t>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL)
+        );
 
         REQUIRE(copts.connectProperties == &opts.get_properties().c_struct());
     }
@@ -317,7 +319,9 @@ TEST_CASE("connect_options copy_assignment", "[options]")
         // Check that we got the correct properties
         REQUIRE(1 == opts.get_properties().size());
         REQUIRE(opts.get_properties().contains(property::SESSION_EXPIRY_INTERVAL));
-        REQUIRE(42 == get<int>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL));
+        REQUIRE(
+            42 == get<uint32_t>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL)
+        );
 
         REQUIRE(copts.connectProperties == &opts.get_properties().c_struct());
     }
@@ -381,7 +385,9 @@ TEST_CASE("connect_options move_assignment", "[options]")
         // Check that we got the correct properties
         REQUIRE(1 == opts.get_properties().size());
         REQUIRE(opts.get_properties().contains(property::SESSION_EXPIRY_INTERVAL));
-        REQUIRE(42 == get<int>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL));
+        REQUIRE(
+            42 == get<uint32_t>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL)
+        );
 
         REQUIRE(copts.connectProperties == &opts.get_properties().c_struct());
     }
@@ -682,7 +688,9 @@ TEST_CASE("connect_options_builder copy_assignment", "[options]")
         // Check that we got the correct properties
         REQUIRE(1 == opts.get_properties().size());
         REQUIRE(opts.get_properties().contains(property::SESSION_EXPIRY_INTERVAL));
-        REQUIRE(42 == get<int>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL));
+        REQUIRE(
+            42 == get<uint32_t>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL)
+        );
     }
 }
 
@@ -739,6 +747,8 @@ TEST_CASE("connect_options_builder move_assignment", "[options]")
         // Check that we got the correct properties
         REQUIRE(1 == opts.get_properties().size());
         REQUIRE(opts.get_properties().contains(property::SESSION_EXPIRY_INTERVAL));
-        REQUIRE(42 == get<int>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL));
+        REQUIRE(
+            42 == get<uint32_t>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL)
+        );
     }
 }

test/unit/test_disconnect_options.cpp

@@ -116,7 +116,9 @@ TEST_CASE("disconnect_options copy ctor", "[options]")
         // Check that the properties transferred over
         REQUIRE(1 == opts.get_properties().size());
         REQUIRE(opts.get_properties().contains(property::SESSION_EXPIRY_INTERVAL));
-        REQUIRE(42 == get<int>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL));
+        REQUIRE(
+            42 == get<uint32_t>(opts.get_properties(), property::SESSION_EXPIRY_INTERVAL)
+        );
 
         REQUIRE(1 == opts.c_struct().properties.count);
         REQUIRE(

test/unit/test_properties.cpp

@@ -78,7 +78,7 @@ TEST_CASE("int property constructor", "[property]")
         REQUIRE(prop.c_struct().value.integer2 == 512);
 
         REQUIRE(prop.type() == typ);
-        REQUIRE(get<int16_t>(prop) == int16_t(512));
+        REQUIRE(get<uint16_t>(prop) == 512);
 
         // Should be able to support full 16-bit unsigned range
         const uint16_t MAX = std::numeric_limits<uint16_t>::max();
@@ -103,7 +103,7 @@ TEST_CASE("int property constructor", "[property]")
         REQUIRE(prop.c_struct().value.integer4 == 70000);
 
         REQUIRE(prop.type() == typ);
-        REQUIRE(get<int32_t>(prop) == int32_t(70000));
+        REQUIRE(get<uint32_t>(prop) == 70000);
 
         // Should be able to support full 32-bit unsigned range
         const uint32_t MAX = std::numeric_limits<uint32_t>::max();
@@ -235,7 +235,7 @@ TEST_CASE("int property copy constructor", "[property]")
         REQUIRE(prop.c_struct().value.integer4 == 70000);
 
         REQUIRE(prop.type() == typ);
-        REQUIRE(get<int32_t>(prop) == int32_t(70000));
+        REQUIRE(get<uint32_t>(prop) == 70000);
     }
 }
 
@@ -252,7 +252,7 @@ TEST_CASE("int property move constructor", "[property]")
         REQUIRE(prop.c_struct().value.integer4 == 70000);
 
         REQUIRE(prop.type() == typ);
-        REQUIRE(get<int32_t>(prop) == int32_t(70000));
+        REQUIRE(get<uint32_t>(prop) == 70000);
 
         // Make sure the old value was moved
         REQUIRE(org_prop.c_struct().identifier == 0);
@@ -434,7 +434,7 @@ TEST_CASE("properties constructors", "[properties]")
         REQUIRE(props.size() == 2);
 
         REQUIRE(42 == get<uint8_t>(props, property::PAYLOAD_FORMAT_INDICATOR));
-        REQUIRE(70000 == get<int>(props, property::MESSAGE_EXPIRY_INTERVAL));
+        REQUIRE(70000 == get<uint32_t>(props, property::MESSAGE_EXPIRY_INTERVAL));
     }
 }