Documentation fixes

Summary: related to T13767

Reviewers: ivica

Reviewed By: ivica

Subscribers: iljazovic, miljen

Differential Revision: https://repo.mireo.local/D31723

doc/qbk/03_auto_reconnect.qbk

@@ -19,7 +19,7 @@ In situations where the connection is unexpectedly lost mid-protocol flow,
 the __Client__ complies with the MQTT protocol's specified message delivery retry mechanisms.
 
 The following example will showcase how the __Client__ internally manages various scenarios, including successful transmission, offline queuing,
-and connection loss retransmissions, when executing a request to publish a message with QoS 1.
+and connection loss retransmissions when executing a request to publish a message with QoS 1.
 Note that the same principle applies to all other asynchronous functions within the __Client__ 
 (see /Completion condition/ under [refmem mqtt_client async_publish], [refmem mqtt_client async_subscribe], [refmem mqtt_client async_unsubscribe],
 and [refmem mqtt_client async_disconnect]).
@@ -75,7 +75,7 @@ such as when a device connected to the network loses its GSM connectivity.
 However, the connection may be closed (or never established) for other reasons,
 which are typically related to misconfiguration of broker IPs, ports, expired or incorrect TLS, or MQTT-related errors,
 such as trying to communicate with a Broker that does not support MQTT 5.
-In these cases, the __Client__ will still endlessly try to connect to Broker(s), but the connection will never succeed.
+In these cases, the __Client__ will still endlessly try to connect to the Broker(s), but the connection will never succeed.
 
 The most challenging problem here is that users of the __Client__ do not get informed in any way that the connection cannot be established.
 So, if you make a typo in the Broker's IP, run the __Client__, and publish some message, the [refmem mqtt_client async_publish] callback will never be invoked,

doc/qbk/04_maintaining_a_stable_connection.qbk

@@ -77,12 +77,12 @@ which responds with __PINGRESP__ packet, affirming its operational status.
 
 The __Client__ will dispatch a __PINGREQ__ at an interval equal to the negotiated `Keep Alive` seconds and expects
 to receive some data
-[footnote The __Client__ does not require to specifically receive __PINGRESP__ to its __PINGREQ__. Any data from the Broker will suffice to confirm its status.]
+[footnote The __Client__ is not required to specifically receive __PINGRESP__ to its __PINGREQ__. Any data from the Broker will suffice to confirm its status.]
 from the Broker within `1.5` times the negotiated `Keep Alive` seconds.
 If no data is received within this time, the __Client__ will assume a half-open state and initiate a reconnect procedure
 described in the [link async_mqtt5.auto_reconnect Built-in auto-reconnect and retry mechanism].
 
-[important If the negotiated `Keep Alive` value is set to `0`, the timeout mechanism to detect half-open connection
+[important If the negotiated `Keep Alive` value is set to `0`, the timeout mechanism to detect a half-open connection
 is disabled. As a result, the __Client__ loses its capability to identify and adequately respond to half-open scenarios.]
 
 [endsect] [/half_open_connections]

doc/qbk/05_optimising_communication.qbk

@@ -8,7 +8,7 @@
 [nochunk]
 
 This chapter provides a detailed breakdown of how __Client__ optimises its communications with the Broker
-with multiflight mode for simultanious message handling and strategies for efficient bandwidth usage.
+with multiflight mode for simultaneous message handling and strategies for efficient bandwidth usage.
 These techniques are key to getting the most out of MQTT in scenarios demanding fast and
 dependable message delivery, all while meeting the protocol's quality of service requirements and network efficiency standards.
 
@@ -19,7 +19,7 @@ This allows the initiation of multiple asynchronous requests simultaneously, wit
 With this feature, you can repeatedly call [refmem mqtt_client async_publish] or any similar `async_xxx` function
 without waiting for the handler invocation of the previous `async_xxx` calls.
 
-This feature is particulary helpful when using __Client__ with callbacks,
+This feature is particularly helpful when using __Client__ with callbacks,
 as it allows you to quickly dispatch multiple requests one after the other,
 instead of nesting them in callbacks.
 
@@ -29,7 +29,7 @@ sending a __PUBLISH__ packet, receiving a __PUBREC__ acknowledgement from the Br
 transmitting a __PUBREL__ packet, and finally receiving a __PUBCOMP__ packet, confirming successful message delivery.
 
 Despite the complexity of initiating several such message exchange sequences consecutively,
-the __Client__ will manage all intermediate packet exchange between the __Client__ and the Broker correctly and complete the message delivery.
+the __Client__ will manage all intermediate packet exchanges between the __Client__ and the Broker correctly and complete the message delivery.
 
 It is important to note that there is no guarantee that the final handlers will be invoked
 in the same order as the corresponding `async_xxx` calls were initiated.

doc/qbk/06_disconnecting_the_client.qbk

@@ -15,7 +15,7 @@ Invoking [refmem mqtt_client cancel] results in the __Client__ closing the conne
 asynchronous operations.
 On the other hand, [refmem mqtt_client async_disconnect] will first attempt to send a __DISCONNECT__ packet
 [footnote The __Client__ will attempt to send the __DISCONNECT__ packet for `5 seconds`. Regardless of the outcome, the connection will be closed.]
-to the Broker in order to notify it about the reason for disconnection,
+to the Broker to notify it about the reason for disconnection,
 then close the connection and cancel all outstanding asynchronous operations (equal effect as [refmem mqtt_client cancel]).
 
 [important Regardless of the method used to stop the __Client__, it is recommended to ensure that all the previous asynchronous operations are
@@ -71,7 +71,7 @@ packets in the queue. However, __DISCONNECT__ packets are prioritised and sent e
 Therefore, the connection will terminate immediately.
 
 If the __Client__ cannot establish a connection to the Broker,
-it will be stopped after `5 seconds`, which is the amount of time the it will spend
+it will be stopped after `5 seconds`, which is the amount of time it will spend
 trying to send the __DISCONNECT__ packet to the Broker before quitting.
 This timeout mechanism ensures that the __Client__ does not indefinitely wait to disconnect,
 preserving resources and maintaining efficient operation.

doc/qbk/15_examples.qbk

@@ -42,7 +42,7 @@ The following list contains all the examples that showcase how to use the __Clie
 		[[link async_mqtt5.timeout_with_parallel_group timeout_with_parallel_group.cpp]]
 		[
 			Shows how to use the __Client__ with its support for per-operation cancellation to perform operations under a time constraint
-			using parallel group.
+			using a parallel group.
 		]
 	]
 	[

include/async_mqtt5/impl/replies.hpp

@@ -102,7 +102,7 @@ private:
 
 public:
 	template <typename Executor>
-	explicit replies(Executor ex) : _ex(ex) {}
+	explicit replies(Executor ex) : _ex(std::move(ex)) {}
 
 	replies(replies&&) = default;
 	replies(const replies&) = delete;

include/async_mqtt5/mqtt_client.hpp

@@ -189,9 +189,9 @@ public:
 	 *
 	 * \par Completion condition
 	 * The asynchronous operation will complete with
-	 * `boost::asio::error::operation_aborted` when client is cancelled by calling
+	 * `boost::asio::error::operation_aborted` when the client is cancelled by calling
 	 * \ref mqtt_client::async_disconnect, \ref mqtt_client::cancel, destruction or
-	 * if non-recoverable error happens during connection attempt (e.g. access denied).
+	 * if a non-recoverable error happens during a connection attempt (e.g. access denied).
 	 *
 	 *	\par Error codes
 	 *	The list of all possible error codes that this operation can finish with:\n
@@ -795,7 +795,7 @@ public:
 	 *
 	 * \details The Client will receive and complete deliveries for all the
 	 * \__PUBLISH\__ packets received from the Broker throughout its lifetime.
-	 * The Client will store them internally in order they were delivered.
+	 * The Client will store them internally in the order they were delivered.
 	 * Calling this function will attempt to receive an Application Message
 	 * from internal storage.
 	 *
@@ -859,7 +859,7 @@ public:
 	 * See \ref mqtt_client::cancel.
 	 *
 	 * \param reason_code Reason Code to notify
-	 * the Broker of the reason for disconnection.
+	 * the Broker of the reason for the disconnection.
 	 * \param props An instance of \__DISCONNECT_PROPS\__.
 	 * \param token Completion token that will be used to produce a
 	 * completion handler. The handler will be invoked when the operation completes.
@@ -884,7 +884,7 @@ public:
 	 *	The list of all possible error codes that this operation can finish with:\n
 	 *		- `boost::system::errc::errc_t::success`\n
 	 *		- `boost::asio::error::operation_aborted`[footnote
-				This error code can appear if the Client failed to send the \__DISCONNECT\__ packet to the Server.
+				This error code can appear if the Client fails to send the \__DISCONNECT\__ packet to the Server.
 				Regardless, the connection to the Server is terminated, and the Client is cancelled.
 			]\n
 	 *		- \link async_mqtt5::client::error::malformed_packet \endlink
@@ -948,7 +948,7 @@ public:
 	 *	The list of all possible error codes that this operation can finish with:\n
 	 *		- `boost::system::errc::errc_t::success`\n
 	 *		- `boost::asio::error::operation_aborted`[footnote
-				This error code can appear if the Client failed to send the \__DISCONNECT\__ packet to the Server.
+				This error code can appear if the Client fails to send the \__DISCONNECT\__ packet to the Server.
 				Regardless, the connection to the Server is terminated, and the Client is cancelled.
 			]\n
 	 *		- \link async_mqtt5::client::error::malformed_packet \endlink

include/async_mqtt5/reason_codes.hpp

@@ -61,7 +61,7 @@ public:
 	/**
 	 * \brief Indication if the object holds a Reason Code indicating an error.
 	 *
-	 * \details Any Reason Code holding a value equal or greater than 0x80.
+	 * \details Any Reason Code holding a value equal to or greater than 0x80.
 	 */
 	explicit operator bool() const noexcept {
 		return _code >= 0x80;
@@ -118,7 +118,7 @@ public:
 				return "Initiate a re-authentication";
 			case 0x80:
 				return "The Server does not wish to reveal the reason for the"
-						"failure, or none of the other Reason Codes apply";
+						"failure or none of the other Reason Codes apply";
 			case 0x81:
 				return "Data within the packet could not be correctly parsed";
 			case 0x82:
@@ -159,7 +159,7 @@ public:
 			case 0x92:
 				return "The Packet Identifier is not known";
 			case 0x93:
-				return "The Client or Server has received more than Receive "
+				return "The Client or Server has received more than the Receive "
 						"Maximum publication for which it has not sent PUBACK or PUBCOMP";
 			case 0x94:
 				return "The Client or Server received a PUBLISH packet containing "
@@ -239,7 +239,7 @@ constexpr reason_code continue_authentication { 0x18 };
 constexpr reason_code reauthenticate { 0x19 };
 
 /** The Server does not wish to reveal the reason for the
- failure, or none of the other Reason Codes apply. */
+ failure or none of the other Reason Codes apply. */
 constexpr reason_code unspecified_error { 0x80 };
 
 /** Data within the packet could not be correctly parsed. */
@@ -298,7 +298,7 @@ constexpr reason_code packet_identifier_in_use { 0x91 };
 /** The Packet Identifier is not known. */
 constexpr reason_code packet_identifier_not_found { 0x92 };
 
-/** The Client or Server has received more than Receive
+/** The Client or Server has received more than the Receive
  Maximum publication for which it has not sent PUBACK or PUBCOMP. */
 constexpr reason_code receive_maximum_exceeded { 0x93 };
 

include/async_mqtt5/types.hpp

@@ -17,12 +17,12 @@
 
 namespace async_mqtt5 {
 
-/** An alias for `boost::system::error_code`; */
+/** An alias for `boost::system::error_code`. */
 using error_code = boost::system::error_code;
 
 /**
  * \brief A data structure used to store information related to an authority
- * such as the host name, port, and path.
+ * such as the hostname, port, and path.
  */
 struct authority_path {
 	std::string host, port, path;
@@ -72,16 +72,16 @@ enum class dup_e : std::uint8_t {
  * \brief Represents the stage of \__ENHANCED_AUTH\__ process.
  */
 enum class auth_step_e {
-	/** Client needs to send initial authentication data. */
+	/** The Client needs to send initial authentication data. */
 	client_initial,
 
 	/** Server responded with reason_codes.continue_authentication and possibly
-	 * authentication data, client needs to send further authentication data.
+	 * authentication data, the Client needs to send further authentication data.
 	 */
 	server_challenge,
 
 	/** Server responded with reason_codes.success and final
-	 * authentication data, which client validates.
+	 * authentication data, which the Client validates.
 	 */
 	server_final
 };