[mqtt-client] slightly better error code documentation

Summary: related to T12804 Reviewers: ivica Reviewed By: ivica Subscribers: miljen, iljazovic Differential Revision: https://repo.mireo.local/D26165
2023-10-19 15:05:22 +02:00
parent 62d7eb21b2
commit 7cb1a877a3
9 changed files with 109 additions and 27 deletions
--- a/doc/qbk/00_main.qbk
+++ b/doc/qbk/00_main.qbk
@ -28,6 +28,8 @@
 [template beastconceptslink[id term][@boost:/libs/beast/doc/html/beast/concepts/[id].html [term]]]
 [template mqttlink[id text][@https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc[id] [text]]]

+[def __ASIO_PER_OP_CANCELLATION__ [@boost:/doc/html/boost_asio/overview/core/cancellation.html Per-Operation Cancellation]]
+
 [def __CompletionToken__ [@boost:/doc/html/boost_asio/reference/asynchronous_operations.html#boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers ['CompletionToken]]]
 [def __ExecutionContext__ [reflink2 ExecutionContext ['ExecutionContext]]]
 [def __StreamType__ [reflink2 StreamType ['StreamType]]]
@ -42,7 +44,9 @@

 [def __UTF8_STRING_PAIR__ [mqttlink 3901013 `UTF-8 String Pair`]]
 [def __PACKET_SIZE__ [mqttlink 3901024 `packet size`]]
-
+[def __MAXIMUM_QOS__ [mqttlink 3901084 `Maximum QoS`]]
+[def __RETAIN_AVAILABLE__ [mqttlink 3901085 `Retain Available`]]
+[def __TOPIC_ALIAS_MAX__ [mqttlink 3901051 `Topic Alias Maximum`]]
 [def __QOS__ [mqttlink 3901234 `QoS`]]
 [def __SUBSCRIBE_OPTIONS__ [mqttlink 3901169 `Subscribe Options`]]

@ -78,7 +82,10 @@
 [def __AUTH_PROPS__ [reflink2 auth_props async_mqtt5::auth_props]]

 [def __ERROR_CODE__ [reflink2 error_code `async_mqtt5::error_code`]]
-[def __REASON_CODE__ [reflink2 Reason_codes `async_mqtt5::reason_code`]]
+[def __REASON_CODE__ [reflink2 reason_code `async_mqtt5::reason_code`]]
+
+[def __REASON_CODES__ [reflink2 Reason_codes `Reason Codes`]]
+[def __ERROR_HANDLING__ [reflink2 Error_handling `Error handling`]]

 [include 01_intro.qbk]

@ -87,9 +94,12 @@

 [block'''<part label="Two: Reference">''']
 [include reference.qbk]
-[include reference/ExecutionContext.qbk]
-[include reference/StreamType.qbk]
-[include reference/TlsContext.qbk]
+
+[include reference/Error_handling.qbk]
+
+[include reference/concepts/ExecutionContext.qbk]
+[include reference/concepts/StreamType.qbk]
+[include reference/concepts/TlsContext.qbk]

 [include reference/reason_codes/Reason_codes.qbk]

--- a/doc/qbk/reference/Error_handling.qbk
+++ b/doc/qbk/reference/Error_handling.qbk
@ -0,0 +1,52 @@
+[/
+    Copyright (c) 2023 Mireo
+   
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section:async_mqtt5__Error_handling Error handling]
+
+The table below provides a reference of all __ERROR_CODE__ instances that asynchronous operations
+may complete with, along with the reasons for their occurrence.
+
+[table:error_codes Error codes
+	[[Error code] [Cause]]
+	[[`boost::system::errc::errc_t::success`] [The operation completed successfully.]]
+	[[`boost::asio::error::opreation_aborted`] [
+		The operation has been cancelled. 
+		The cancellation of the operation can be triggered by invoking either [refmem mqtt_client cancel]
+		or [refmem mqtt_client async_disconnect]. Furthermore, if a cancellation slot has been associated
+		with the __CompletionToken__ provided and the corresponding cancellation signal is emitted,
+		the operation will also finish with this error code (see __ASIO_PER_OP_CANCELLATION__).
+	]]
+	[[`boost::asio::experimental::error::channel_cancelled`] [
+		This error occurs in scenarios identical to those causing `boost::asio::error::operation_aborted` 
+		error code but it is exclusive to completion handlers associated with [refmem mqtt_client async_receive] calls.
+	]]
+	[[`async_mqtt5::client::error::pid_overrun`] [
+		This error code signifies that the Client was unable to allocate a Packet Identifier for
+		the current operation due to the exhaustion of the available identifiers.
+		This occurs when there are 65535 outgoing Packets awaiting their responses.
+	]]
+	[[`async_mqtt5::client::error::qos_not_supported`] [
+		The Client has attempted to publish an Application Message with __QOS__ higher
+		than the Maximum __QOS__ specified by the Server.
+		The Server does not support this __QOS__ (see __MAXIMUM_QOS__).
+		This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish] calls.
+	]]
+	[[`async_mqtt5::client::error::retain_not_available`] [
+		The Client has attempted to publish an Application Message with the RETAIN flag set to 1.
+		However, the Server does not support retained messages (see __RETAIN_AVAILABLE__).
+		This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish] calls.
+	]]
+	[[`async_mqtt5::client::error::topic_alias_maximum`] [
+		The Client has attempted to publish an Application Message with the Topic Alias 
+		exceeding the Server's supported Topic Alias Maximum. Additionally, this error code
+		will arise in instances when the Server does NOT support Topic Aliases, and the 
+		Client has attempted to use them. See __TOPIC_ALIAS_MAX__.
+		This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish] calls.
+	]]
+]
+
+[endsect]
--- a/doc/qbk/reference/concepts/ExecutionContext.qbk
+++ b/doc/qbk/reference/concepts/ExecutionContext.qbk
--- a/doc/qbk/reference/concepts/StreamType.qbk
+++ b/doc/qbk/reference/concepts/StreamType.qbk
--- a/doc/qbk/reference/concepts/TlsContext.qbk
+++ b/doc/qbk/reference/concepts/TlsContext.qbk
--- a/doc/qbk/reference/quickref.xml
+++ b/doc/qbk/reference/quickref.xml
@ -41,12 +41,6 @@
          <member><link linkend="async_mqtt5.ref.async_mqtt5__qos_e">qos_e</link></member>
          <member><link linkend="async_mqtt5.ref.async_mqtt5__retain_e">retain_e</link></member>
        </simplelist>
-      </entry>
-      <entry valign="top">
-        <bridgehead renderas="sect3">Constants</bridgehead>
-          <member><link linkend="async_mqtt5.ref.async_mqtt5__Reason_codes">Reason codes</link></member>
-        <simplelist type="vert" columns="1">
-        </simplelist>
        <bridgehead renderas="sect3">Functions</bridgehead>
        <simplelist type="vert" columns="1">
          <member><link linkend="async_mqtt5.ref.async_mqtt5__client__get_error_code_category">get_error_code_category</link></member>
@ -72,6 +66,13 @@
          <member><link linkend="async_mqtt5.ref.async_mqtt5__auth_props">auth_props</link></member>
        </simplelist>
      </entry>
+      <entry valign="top">
+        <bridgehead renderas="sect3">Reference tables</bridgehead>
+        <simplelist type="vert" columns="1">
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__Reason_codes">Reason codes</link></member>
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__Error_handling">Error handling</link></member>
+        </simplelist>
+      </entry>
    </row></tbody>
  </tgroup>
 </informaltable>
--- a/doc/qbk/reference/reason_codes/Reason_codes.qbk
+++ b/doc/qbk/reference/reason_codes/Reason_codes.qbk
@ -5,11 +5,10 @@
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]

-
 [section:async_mqtt5__Reason_codes Reason codes]

-This section lists all possible [reflink2 reason_code reason codes] that can be sent in a
-MQTT Control Packet.
+This section lists all possible __REASON_CODE__ instances representing
+Reason Codes that can be found in MQTT Control Packets.

 [xinclude rcref.xml]

--- a/include/async_mqtt5/error.hpp
+++ b/include/async_mqtt5/error.hpp
@ -47,8 +47,10 @@ enum class error : int {
 	/** [unused] A fatal error occurred. */
 	fatal_error = 100,

+	/// \cond INTERNAL
 	/** Malformed packet has been detected. */
 	malformed_packet,
+	/// \endcond

 	/** There are no more available Packet Identifiers to use. */
 	pid_overrun,
@ -56,7 +58,7 @@ enum class error : int {
 	/** [unused] The Client has reconnected. */
 	reconnected,

-	/** The Client has been disconnected. */
+	/** [unused] The Client has been disconnected. */
 	disconnected,

 	// publish
@ -142,6 +144,8 @@ enum class category : uint8_t {
 *	The \__CONNACK\__,  \__PUBACK\__,  \__PUBREC\__,  \__PUBREL\__,  \__PUBCOMP\__,  \__DISCONNECT\__
 *	and  \__AUTH\__ Control Packets have a single Reason Code as part of the Variable Header.
 *	The \__SUBACK\__ and \__UNSUBACK\__ packets contain a list of one or more Reason Codes in the Payload.
+ *
+ *	\see See \__REASON_CODES\__ for a complete list of all possible instances of this class.
 */
 class reason_code {
 	uint8_t _code;
--- a/include/async_mqtt5/mqtt_client.hpp
+++ b/include/async_mqtt5/mqtt_client.hpp
@ -184,12 +184,12 @@ public:
 	 * \param hosts List of Broker addresses and ports.
 	 * Address and ports are separated with a colon `:` while
 	 * pairs of addresses and ports are separated with a comma `,`.
-	 * \param default_port Default port to connect to in case the port is not
-	 * explicitly specified in the hosts list.
+	 * \param default_port The default port to connect to in case the port is not
+	 * explicitly specified in the `hosts` list.
 	 *
 	 *
 	 * \par Example
-	 * Some valid hosts string:
+	 * Some valid `hosts` string:
 	 *
 	 * \code
 	 *		std::string valid_hosts_1 = "broker1:1883, broker2, broker3:1883";
@ -247,11 +247,13 @@ public:
 	 *	\par Error codes
 	 *	The list of all possible error codes that this operation can finish with:\n
 	 *		- `boost::system::errc::errc_t::success`\n
-	 *		- `boost::asio::operation_aborted` \n
+	 *		- `boost::asio::error::operation_aborted` \n
 	 *		- \link client::error::pid_overrun \endlink
 	 *		- \link client::error::qos_not_supported \endlink
 	 *		- \link client::error::retain_not_available \endlink
 	 *		- \link client::error::topic_alias_maximum_reached \endlink
+	 *
+	 * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
 	 */
 	template <qos_e qos_type, typename CompletionToken>
 	decltype(auto) async_publish(
@ -311,8 +313,10 @@ public:
 	 *	\par Error codes
 	 *	The list of all possible error codes that this operation can finish with:\n
 	 *		- `boost::system::errc::errc_t::success`\n
-	 *		- `boost::asio::operation_aborted` \n
+	 *		- `boost::asio::error::operation_aborted` \n
 	 *		- \link client::error::pid_overrun \endlink
+	 *
+	 * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
 	 */
 	template <typename CompletionToken>
 	decltype(auto) async_subscribe(
@ -366,8 +370,10 @@ public:
 	 *	\par Error codes
 	 *	The list of all possible error codes that this operation can finish with:\n
 	 *		- `boost::system::errc::errc_t::success`\n
-	 *		- `boost::asio::operation_aborted` \n
+	 *		- `boost::asio::error::operation_aborted` \n
 	 *		- \link client::error::pid_overrun \endlink
+	 *
+	 * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
 	 */
 	template <typename CompletionToken>
 	decltype(auto) async_subscribe(
@ -409,8 +415,10 @@ public:
 	 *	\par Error codes
 	 *	The list of all possible error codes that this operation can finish with:\n
 	 *		- `boost::system::errc::errc_t::success`\n
-	 *		- `boost::asio::operation_aborted` \n
+	 *		- `boost::asio::error::operation_aborted` \n
 	 *		- \link client::error::pid_overrun \endlink
+	 *
+	 * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
 	 */
 	template <typename CompletionToken>
 	decltype(auto) async_unsubscribe(
@ -453,7 +461,7 @@ public:
 	 *	\code
 	 *		void (
 	 *			__ERROR_CODE__, // Result of operation.
-	 *			std::vector<__REASON__CODE__>,	// Vector of Reason Codes containing
+	 *			std::vector<__REASON_CODE__>,	// Vector of Reason Codes containing
 	 *													// the result of unsubscribe operation
 	 *													// for the Topic in the UNSUBSCRIBE packet.
 	 *			__UNSUBACK_PROPS__, // Properties received in the UNSUBACK packet.
@ -463,8 +471,10 @@ public:
 	 *	\par Error codes
 	 *	The list of all possible error codes that this operation can finish with:\n
 	 *		- `boost::system::errc::errc_t::success`\n
-	 *		- `boost::asio::operation_aborted` \n
+	 *		- `boost::asio::error::operation_aborted` \n
 	 *		- \link client::error::pid_overrun \endlink
+	 *
+	 * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
 	 */
 	template <typename CompletionToken>
 	decltype(auto) async_unsubscribe(
@ -508,7 +518,9 @@ public:
 	 *	\par Error codes
 	 *	The list of all possible error codes that this operation can finish with:\n
 	 *		- `boost::system::errc::errc_t::success`\n
-	 *		- `boost::experimental::error::channel_cancelled`
+	 *		- `boost::asio::experimental::error::channel_cancelled`
+	 *
+	 * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
 	 */
 	template <typename CompletionToken>
 	decltype(auto) async_receive(CompletionToken&& token) {
@ -543,8 +555,10 @@ public:
 	 *	\par Error codes
 	 *	The list of all possible error codes that this operation can finish with:\n
 	 *		- `boost::system::errc::errc_t::success`\n
-	 *		- `boost::asio::operation_aborted`\n
+	 *		- `boost::asio::error::operation_aborted`\n
 	 *		- `boost::asio::no_recovery`\n
+	 *
+	 * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
 	 */
 	template <typename CompletionToken>
 	decltype(auto) async_disconnect(
@ -580,8 +594,10 @@ public:
 	 *	\par Error codes
 	 *	The list of all possible error codes that this operation can finish with:\n
 	 *		- `boost::system::errc::errc_t::success`\n
-	 *		- `boost::asio::operation_aborted`\n
+	 *		- `boost::asio::error::operation_aborted`\n
 	 *		- `boost::asio::no_recovery`\n
+	 *
+	 * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
 	 */
 	template <typename CompletionToken>
 	decltype(auto) async_disconnect(CompletionToken&& token) {