[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

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]
 

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]

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>

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]