From 62d7eb21b22eca01038989c6631e5403ccf18c67 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Korina=20=C5=A0imi=C4=8Devi=C4=87?= <korina@mireo.local>
Date: Wed, 18 Oct 2023 12:16:05 +0200
Subject: [PATCH] [mqtt-client] A lot of various document changes

Summary:
related to T12804

- property files are now lowercase and match code names

- properties properly link to their pages

- packet names do not automatically link anymore

- TlsContext documented

- types inside handler signatures properly link to their pages

next up: better error code documentation

Reviewers: ivica

Reviewed By: ivica

Subscribers: miljen, iljazovic

Differential Revision: https://repo.mireo.local/D26155
---
 doc/Jamfile                                   |   1 +
 doc/qbk/00_main.qbk                           |  83 +++++---
 doc/qbk/reference/TlsContext.qbk              |   3 +-
 .../{AUTH_props.qbk => auth_props.qbk}        |   6 +-
 .../{CONNACK_props.qbk => connack_props.qbk}  |  10 +-
 .../{CONNECT_props.qbk => connect_props.qbk}  |  15 +-
 ...CONNECT_props.qbk => disconnect_props.qbk} |   6 +-
 .../{PUBACK_props.qbk => puback_props.qbk}    |   6 +-
 .../{PUBCOMP_props.qbk => pubcomp_props.qbk}  |   6 +-
 .../{PUBLISH_props.qbk => publish_props.qbk}  |   6 +-
 .../{PUBREC_props.qbk => pubrec_props.qbk}    |   6 +-
 .../{PUBREL_props.qbk => pubrel_props.qbk}    |   6 +-
 .../{SUBACK_props.qbk => suback_props.qbk}    |   6 +-
 ...UBSCRIBE_props.qbk => subscribe_props.qbk} |   6 +-
 ...{UNSUBACK_props.qbk => unsuback_props.qbk} |   6 +-
 ...SCRIBE_props.qbk => unsubscribe_props.qbk} |   6 +-
 .../{Will_props.qbk => will_props.qbk}        |   7 +-
 doc/qbk/reference/quickref.xml                |  28 +--
 .../reference/reason_codes/Reason_codes.qbk   |   2 +-
 doc/xsl/custom-overrides.xsl                  |   1 +
 include/async_mqtt5/error.hpp                 |  28 +--
 include/async_mqtt5/impl/disconnect_op.hpp    |   1 +
 include/async_mqtt5/mqtt_client.hpp           | 177 ++++++++++--------
 include/async_mqtt5/types.hpp                 |  15 +-
 24 files changed, 248 insertions(+), 189 deletions(-)
 rename doc/qbk/reference/properties/{AUTH_props.qbk => auth_props.qbk} (87%)
 rename doc/qbk/reference/properties/{CONNACK_props.qbk => connack_props.qbk} (88%)
 rename doc/qbk/reference/properties/{CONNECT_props.qbk => connect_props.qbk} (74%)
 rename doc/qbk/reference/properties/{DISCONNECT_props.qbk => disconnect_props.qbk} (84%)
 rename doc/qbk/reference/properties/{PUBACK_props.qbk => puback_props.qbk} (83%)
 rename doc/qbk/reference/properties/{PUBCOMP_props.qbk => pubcomp_props.qbk} (83%)
 rename doc/qbk/reference/properties/{PUBLISH_props.qbk => publish_props.qbk} (90%)
 rename doc/qbk/reference/properties/{PUBREC_props.qbk => pubrec_props.qbk} (83%)
 rename doc/qbk/reference/properties/{PUBREL_props.qbk => pubrel_props.qbk} (83%)
 rename doc/qbk/reference/properties/{SUBACK_props.qbk => suback_props.qbk} (83%)
 rename doc/qbk/reference/properties/{SUBSCRIBE_props.qbk => subscribe_props.qbk} (83%)
 rename doc/qbk/reference/properties/{UNSUBACK_props.qbk => unsuback_props.qbk} (82%)
 rename doc/qbk/reference/properties/{UNSUBSCRIBE_props.qbk => unsubscribe_props.qbk} (82%)
 rename doc/qbk/reference/properties/{Will_props.qbk => will_props.qbk} (87%)

diff --git a/doc/Jamfile b/doc/Jamfile
index 43610b3..f846fd0 100644
--- a/doc/Jamfile
+++ b/doc/Jamfile
@@ -40,6 +40,7 @@ import ../../../../3rdParty/boost-doc/docca/docca.jam ;
 local doxygen_exclussions =
 	detail
 	impl
+	property_types.hpp
 ;
 
 docca.reference reference.qbk
diff --git a/doc/qbk/00_main.qbk b/doc/qbk/00_main.qbk
index e1d7796..80b9b6a 100644
--- a/doc/qbk/00_main.qbk
+++ b/doc/qbk/00_main.qbk
@@ -37,25 +37,48 @@
 [def __Asio__ [@boost:/libs/asio/index.html Boost.Asio]]
 [def __Self__ [async_mqtt5]]
 
-[/ MQTT stuff]
+[/ MQTT ]
 [def __MQTT__ [@https://mqtt.org/ MQTT]]
+
 [def __UTF8_STRING_PAIR__ [mqttlink 3901013 `UTF-8 String Pair`]]
 [def __PACKET_SIZE__ [mqttlink 3901024 `packet size`]]
-[def CONNECT [mqttlink 3901033 `CONNECT`]]
-[def CONNACK [mqttlink 3901074 `CONNACK`]]
-[def PUBLISH [mqttlink 3901100 `PUBLISH`]]
-[def PUBACK [mqttlink 3901121 `PUBACK`]]
-[def PUBREC [mqttlink 3901131 `PUBREC`]]
-[def PUBREL [mqttlink 3901141 `PUBREL`]]
-[def PUBCOMP [mqttlink 3901151 `PUBCOMP`]]
-[def SUBSCRIBE [mqttlink 3901161 `SUBSCRIBE`]]
-[def SUBACK [mqttlink 3901171 `SUBACK`]]
-[def UNSUBSCRIBE [mqttlink 3901179 `UNSUBSCRIBE`]]
-[def UNSUBACK [mqttlink 3901187 `UNSUBACK`]]
-[def PINGREQ [mqttlink 3901195 `PINGREQ`]]
-[def PINGRESP [mqttlink 3901200 `PINGRESP`]]
-[def DISCONNECT [mqttlink 3901205 `DISCONNECT`]]
-[def AUTH [mqttlink 3901217 `AUTH`]]
+
+[def __QOS__ [mqttlink 3901234 `QoS`]]
+[def __SUBSCRIBE_OPTIONS__ [mqttlink 3901169 `Subscribe Options`]]
+
+[def __CONNECT__ [mqttlink 3901033 `CONNECT`]]
+[def __CONNACK__ [mqttlink 3901074 `CONNACK`]]
+[def __PUBLISH__ [mqttlink 3901100 `PUBLISH`]]
+[def __PUBACK__ [mqttlink 3901121 `PUBACK`]]
+[def __PUBREC__ [mqttlink 3901131 `PUBREC`]]
+[def __PUBREL__ [mqttlink 3901141 `PUBREL`]]
+[def __PUBCOMP__ [mqttlink 3901151 `PUBCOMP`]]
+[def __SUBSCRIBE__ [mqttlink 3901161 `SUBSCRIBE`]]
+[def __SUBACK__ [mqttlink 3901171 `SUBACK`]]
+[def __UNSUBSCRIBE__ [mqttlink 3901179 `UNSUBSCRIBE`]]
+[def __UNSUBACK__ [mqttlink 3901187 `UNSUBACK`]]
+[def __PINGREQ__ [mqttlink 3901195 `PINGREQ`]]
+[def __PINGRESP__ [mqttlink 3901200 `PINGRESP`]]
+[def __DISCONNECT__ [mqttlink 3901205 `DISCONNECT`]]
+[def __AUTH__ [mqttlink 3901217 `AUTH`]]
+
+[def __WILL_PROPS__ [reflink2 will_props async_mqtt5::will_props]]
+[def __CONNECT_PROPS__ [reflink2 connect_props async_mqtt5::connect_props]]
+[def __CONNACK_PROPS__ [reflink2 connack_props async_mqtt5::connack_props]]
+[def __PUBLISH_PROPS__ [reflink2 publish_props async_mqtt5::publish_props]]
+[def __PUBACK_PROPS__ [reflink2 puback_props async_mqtt5::puback_props]]
+[def __PUBREC_PROPS__ [reflink2 pubrec_props async_mqtt5::pubrec_props]]
+[def __PUBREL_PROPS__ [reflink2 pubrel_props async_mqtt5::pubrel_props]]
+[def __PUBCOMP_PROPS__ [reflink2 pubcomp_props async_mqtt5::pubcomp_props]]
+[def __SUBSCRIBE_PROPS__ [reflink2 subscribe_props async_mqtt5::subscribe_props]]
+[def __SUBACK_PROPS__ [reflink2 suback_props async_mqtt5::suback_props]]
+[def __UNSUBSCRIBE_PROPS__ [reflink2 unsubscribe_props async_mqtt5::unsubscribe_props]]
+[def __UNSUBACK_PROPS__ [reflink2 unsuback_props async_mqtt5::unsuback_props]]
+[def __DISCONNECT_PROPS__ [reflink2 disconnect_props async_mqtt5::disconnect_props]]
+[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`]]
 
 [include 01_intro.qbk]
 
@@ -70,20 +93,20 @@
 
 [include reference/reason_codes/Reason_codes.qbk]
 
-[include reference/properties/CONNECT_props.qbk]
-[include reference/properties/CONNACK_props.qbk]
-[include reference/properties/Will_props.qbk]
-[include reference/properties/PUBLISH_props.qbk]
-[include reference/properties/PUBACK_props.qbk]
-[include reference/properties/PUBREC_props.qbk]
-[include reference/properties/PUBREL_props.qbk]
-[include reference/properties/PUBCOMP_props.qbk]
-[include reference/properties/SUBSCRIBE_props.qbk]
-[include reference/properties/SUBACK_props.qbk]
-[include reference/properties/UNSUBSCRIBE_props.qbk]
-[include reference/properties/UNSUBACK_props.qbk]
-[include reference/properties/DISCONNECT_props.qbk]
-[include reference/properties/AUTH_props.qbk]
+[include reference/properties/will_props.qbk]
+[include reference/properties/connect_props.qbk]
+[include reference/properties/connack_props.qbk]
+[include reference/properties/publish_props.qbk]
+[include reference/properties/puback_props.qbk]
+[include reference/properties/pubrec_props.qbk]
+[include reference/properties/pubrel_props.qbk]
+[include reference/properties/pubcomp_props.qbk]
+[include reference/properties/subscribe_props.qbk]
+[include reference/properties/suback_props.qbk]
+[include reference/properties/unsubscribe_props.qbk]
+[include reference/properties/unsuback_props.qbk]
+[include reference/properties/disconnect_props.qbk]
+[include reference/properties/auth_props.qbk]
 [block'''</part>''']
 [endsect]
 
diff --git a/doc/qbk/reference/TlsContext.qbk b/doc/qbk/reference/TlsContext.qbk
index 018db3b..440ce5e 100644
--- a/doc/qbk/reference/TlsContext.qbk
+++ b/doc/qbk/reference/TlsContext.qbk
@@ -7,7 +7,8 @@
 
 [section:async_mqtt5__TlsContext TlsContext concept]
 
-// TODO
+`TlsContext` represents an object that defines user's configuration
+for establishing TLS/SSL connections.
 
 The type [asioreflink ssl__context ssl::context] meets these requirements.
 
diff --git a/doc/qbk/reference/properties/AUTH_props.qbk b/doc/qbk/reference/properties/auth_props.qbk
similarity index 87%
rename from doc/qbk/reference/properties/AUTH_props.qbk
rename to doc/qbk/reference/properties/auth_props.qbk
index aadf10f..9092081 100644
--- a/doc/qbk/reference/properties/AUTH_props.qbk
+++ b/doc/qbk/reference/properties/auth_props.qbk
@@ -5,12 +5,12 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:async_mqtt5__AUTH_props AUTH properties]
-The last field in the Variable header of AUTH packet is a set of Properties.
+[section:async_mqtt5__auth_props AUTH properties]
+The last field in the Variable header of __AUTH__ packet is a set of Properties.
 A set contains a Property Length followed by the Properties.
 A Property consists of an Identifier and a value.
 
-This section lists all possible AUTH Properties and describes their usage:
+This section lists all possible __AUTH__ Properties and describes their usage:
 
 [table:auth_props AUTH properties
 	[[Identifier] [Value type] [Description]]
diff --git a/doc/qbk/reference/properties/CONNACK_props.qbk b/doc/qbk/reference/properties/connack_props.qbk
similarity index 88%
rename from doc/qbk/reference/properties/CONNACK_props.qbk
rename to doc/qbk/reference/properties/connack_props.qbk
index 5b4195d..d9a4ed5 100644
--- a/doc/qbk/reference/properties/CONNACK_props.qbk
+++ b/doc/qbk/reference/properties/connack_props.qbk
@@ -5,12 +5,12 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:async_mqtt5__CONNACK_props CONNACK properties]
-The last field in the Variable header of CONNACK packet is a set of Properties.
+[section:async_mqtt5__connack_props CONNACK properties]
+The last field in the Variable header of __CONNACK__ packet is a set of Properties.
 A set contains a Property Length followed by the Properties.
 A Property consists of an Identifier and a value.
 
-This section lists all possible CONNACK Properties and describes their usage:
+This section lists all possible __CONNACK__ Properties and describes their usage:
 
 [table:connack_props CONNACK properties
 	[[Identifier] [Value type] [Description]]
@@ -18,8 +18,8 @@ This section lists all possible CONNACK Properties and describes their usage:
 	[[receive_maximum] [`int16_t`] [The maximum number of QoS 1 and QoS 2 publications that the Server is willing to process concurrently.]]
 	[[maximum_qos] [`uint8_t`] [The highest QoS the Server supports.]]
 	[[retain_available] [`uint8_t`] [A value of 0 means that retained message are not supported. A value of 1 means they are supported.]]
-	[[maximum_packet_size] [`int32_t`] [The maximum __PACKET_SIZE__ in bytes that the Server is willing to accept.]]
-	[[assigned_client_identifier] [`std::string`] [The Client Identifier which was assigned by the Server because a zero length Client Identifier was found in the CONNECT packet]]
+	[[maximum_packet_size] [`int32_t`] [The maximum __PACKET_SIZE__ in bytes as defined by the specification that the Server is willing to accept.]]
+	[[assigned_client_identifier] [`std::string`] [The Client Identifier which was assigned by the Server because a zero length Client Identifier was found in the __CONNECT__ packet]]
 	[[topic_alias_maximum] [`uint16_t`] [The highest value that the Server will accept as a Topic Alias sent by the Client.]]
 	[[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
 	[[correlation_data] [`std::string`] [Binary Data used by the sender of the Request Message to identify which request the Response Message is for when it is received.]]
diff --git a/doc/qbk/reference/properties/CONNECT_props.qbk b/doc/qbk/reference/properties/connect_props.qbk
similarity index 74%
rename from doc/qbk/reference/properties/CONNECT_props.qbk
rename to doc/qbk/reference/properties/connect_props.qbk
index 5d17493..5bb7b01 100644
--- a/doc/qbk/reference/properties/CONNECT_props.qbk
+++ b/doc/qbk/reference/properties/connect_props.qbk
@@ -5,22 +5,23 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:async_mqtt5__CONNECT_props CONNECT properties]
-The last field in the Variable header of CONNECT packet is a set of Properties.
+[section:async_mqtt5__connect_props CONNECT properties]
+The last field in the Variable header of __CONNECT__ packet is a set of Properties.
 A set contains a Property Length followed by the Properties.
 A Property consists of an Identifier and a value.
 
-This section lists all possible CONNECT Properties and describes their usage:
+This section lists all possible __CONNECT__ Properties and describes their usage:
 
 [table:connect_props CONNECT properties
 	[[Identifier] [Value type] [Description]]
 	[[session_expiry_interval] [`int32_t`] [Represents the Session Expiry Internal in seconds.]]
 	[[receive_maximum] [`int16_t`] [The maximum number of QoS 1 and QoS 2 publications that the Client is willing to process concurrently.]]
-	[[maximum_packet_size] [`int32_t`] [The maximum __PACKET_SIZE__ in bytes that the Client is willing to process.]]
+	[[maximum_packet_size] [`int32_t`] [The maximum __PACKET_SIZE__ in bytes as defined by the specification that the Client is willing to process.]]
 	[[topic_alias_maximum] [`uint16_t`] [The highest value that the Client will accept as a Topic Alias sent by the Server.]]
-	[[request_response_information] [`uint8_t`] [The value of 0 signals that the Server MUST NOT return Response Information in CONNACK. If the value if 1, it MAY return it.]]
-	[[request_problem_information] [`uint8_t`] [The value of 0 signals that the Server MAY return a Reason String or User Properties on a CONNACK or DISCONNECT packet, 
-		but MUST NOT send them on any packet other than PUBLISH, CONNACK, or DISCONNECT. If the value is 1, the Server MAY return a Reason String or User Properties where it is allowed.]]
+	[[request_response_information] [`uint8_t`] [The value of 0 signals that the Server MUST NOT return Response Information in __CONNACK__. If the value if 1, it MAY return it.]]
+	[[request_problem_information] [`uint8_t`] [The value of 0 signals that the Server MAY return a Reason String or User Properties on a __CONNACK__ or __DISCONNECT__ packet, 
+		but MUST NOT send them on any packet other than __PUBLISH__, __CONNACK__, or __DISCONNECT__. 
+		If the value is 1, the Server MAY return a Reason String or User Properties where it is allowed.]]
 	[[user_property] [`std::vector<std::string>`] [A list of name, value pairs (__UTF8_STRING_PAIR__) defining User Properties. 
 		The meaning of these properties is not defined by the specification.]]
 	[[authentication_method] [`std::string`] [A UTF-8 Encoded String containing the name of the authentication method used for extended authentication.]]
diff --git a/doc/qbk/reference/properties/DISCONNECT_props.qbk b/doc/qbk/reference/properties/disconnect_props.qbk
similarity index 84%
rename from doc/qbk/reference/properties/DISCONNECT_props.qbk
rename to doc/qbk/reference/properties/disconnect_props.qbk
index 527a9b3..5473616 100644
--- a/doc/qbk/reference/properties/DISCONNECT_props.qbk
+++ b/doc/qbk/reference/properties/disconnect_props.qbk
@@ -5,12 +5,12 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:async_mqtt5__DISCONNECT_props DISCONNECT properties]
-The last field in the Variable header of DISCONNECT packet is a set of Properties.
+[section:async_mqtt5__disconnect_props DISCONNECT properties]
+The last field in the Variable header of __DISCONNECT__ packet is a set of Properties.
 A set contains a Property Length followed by the Properties.
 A Property consists of an Identifier and a value.
 
-This section lists all possible DISCONNECT Properties and describes their usage:
+This section lists all possible __DISCONNECT__ Properties and describes their usage:
 
 [table:disconnect_props DISCONNECT properties
 	[[Identifier] [Value type] [Description]]
diff --git a/doc/qbk/reference/properties/PUBACK_props.qbk b/doc/qbk/reference/properties/puback_props.qbk
similarity index 83%
rename from doc/qbk/reference/properties/PUBACK_props.qbk
rename to doc/qbk/reference/properties/puback_props.qbk
index d28ddde..c14bc5e 100644
--- a/doc/qbk/reference/properties/PUBACK_props.qbk
+++ b/doc/qbk/reference/properties/puback_props.qbk
@@ -5,12 +5,12 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:async_mqtt5__PUBACK_props PUBACK properties]
-The last field in the Variable header of PUBACK packet is a set of Properties.
+[section:async_mqtt5__puback_props PUBACK properties]
+The last field in the Variable header of __PUBACK__ packet is a set of Properties.
 A set contains a Property Length followed by the Properties.
 A Property consists of an Identifier and a value.
 
-This section lists all possible PUBACK Properties and describes their usage:
+This section lists all possible __PUBACK__ Properties and describes their usage:
 
 [table:puback_props PUBACK properties
 	[[Identifier] [Value type] [Description]]
diff --git a/doc/qbk/reference/properties/PUBCOMP_props.qbk b/doc/qbk/reference/properties/pubcomp_props.qbk
similarity index 83%
rename from doc/qbk/reference/properties/PUBCOMP_props.qbk
rename to doc/qbk/reference/properties/pubcomp_props.qbk
index 39ab919..53e8172 100644
--- a/doc/qbk/reference/properties/PUBCOMP_props.qbk
+++ b/doc/qbk/reference/properties/pubcomp_props.qbk
@@ -5,12 +5,12 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:async_mqtt5__PUBCOMP_props PUBCOMP properties]
-The last field in the Variable header of PUBCOMP packet is a set of Properties.
+[section:async_mqtt5__pubcomp_props PUBCOMP properties]
+The last field in the Variable header of __PUBCOMP__ packet is a set of Properties.
 A set contains a Property Length followed by the Properties.
 A Property consists of an Identifier and a value.
 
-This section lists all possible PUBCOMP Properties and describes their usage:
+This section lists all possible __PUBCOMP__ Properties and describes their usage:
 
 [table:pubrec_props PUBCOMP properties
 	[[Identifier] [Value type] [Description]]
diff --git a/doc/qbk/reference/properties/PUBLISH_props.qbk b/doc/qbk/reference/properties/publish_props.qbk
similarity index 90%
rename from doc/qbk/reference/properties/PUBLISH_props.qbk
rename to doc/qbk/reference/properties/publish_props.qbk
index a9fb335..a378ae3 100644
--- a/doc/qbk/reference/properties/PUBLISH_props.qbk
+++ b/doc/qbk/reference/properties/publish_props.qbk
@@ -5,12 +5,12 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:async_mqtt5__PUBLISH_props PUBLISH properties]
-The last field in the Variable header of PUBLISH packet is a set of Properties.
+[section:async_mqtt5__publish_props PUBLISH properties]
+The last field in the Variable header of __PUBLISH__ packet is a set of Properties.
 A set contains a Property Length followed by the Properties.
 A Property consists of an Identifier and a value.
 
-This section lists all possible PUBLISH Properties and describes their usage:
+This section lists all possible __PUBLISH__ Properties and describes their usage:
 
 [table:publish_props PUBLISH properties
 	[[Identifier] [Value type] [Description]]
diff --git a/doc/qbk/reference/properties/PUBREC_props.qbk b/doc/qbk/reference/properties/pubrec_props.qbk
similarity index 83%
rename from doc/qbk/reference/properties/PUBREC_props.qbk
rename to doc/qbk/reference/properties/pubrec_props.qbk
index 27008ab..64ce91c 100644
--- a/doc/qbk/reference/properties/PUBREC_props.qbk
+++ b/doc/qbk/reference/properties/pubrec_props.qbk
@@ -5,12 +5,12 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:async_mqtt5__PUBREC_props PUBREC properties]
-The last field in the Variable header of PUBREC packet is a set of Properties.
+[section:async_mqtt5__pubrec_props PUBREC properties]
+The last field in the Variable header of __PUBREC__ packet is a set of Properties.
 A set contains a Property Length followed by the Properties.
 A Property consists of an Identifier and a value.
 
-This section lists all possible PUBREC Properties and describes their usage:
+This section lists all possible __PUBREC__ Properties and describes their usage:
 
 [table:pubrec_props PUBREC properties
 	[[Identifier] [Value type] [Description]]
diff --git a/doc/qbk/reference/properties/PUBREL_props.qbk b/doc/qbk/reference/properties/pubrel_props.qbk
similarity index 83%
rename from doc/qbk/reference/properties/PUBREL_props.qbk
rename to doc/qbk/reference/properties/pubrel_props.qbk
index 8605c08..a44a29c 100644
--- a/doc/qbk/reference/properties/PUBREL_props.qbk
+++ b/doc/qbk/reference/properties/pubrel_props.qbk
@@ -5,12 +5,12 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:async_mqtt5__PUBREL_props PUBREL properties]
-The last field in the Variable header of PUBREL packet is a set of Properties.
+[section:async_mqtt5__pubrel_props PUBREL properties]
+The last field in the Variable header of __PUBREL__ packet is a set of Properties.
 A set contains a Property Length followed by the Properties.
 A Property consists of an Identifier and a value.
 
-This section lists all possible PUBREL Properties and describes their usage:
+This section lists all possible __PUBREL__ Properties and describes their usage:
 
 [table:pubrec_props PUBREL properties
 	[[Identifier] [Value type] [Description]]
diff --git a/doc/qbk/reference/properties/SUBACK_props.qbk b/doc/qbk/reference/properties/suback_props.qbk
similarity index 83%
rename from doc/qbk/reference/properties/SUBACK_props.qbk
rename to doc/qbk/reference/properties/suback_props.qbk
index 40e7c27..f39142c 100644
--- a/doc/qbk/reference/properties/SUBACK_props.qbk
+++ b/doc/qbk/reference/properties/suback_props.qbk
@@ -5,12 +5,12 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:async_mqtt5__SUBACK_props SUBACK properties]
-The last field in the Variable header of SUBACK packet is a set of Properties.
+[section:async_mqtt5__suback_props SUBACK properties]
+The last field in the Variable header of __SUBACK__ packet is a set of Properties.
 A set contains a Property Length followed by the Properties.
 A Property consists of an Identifier and a value.
 
-This section lists all possible SUBACK Properties and describes their usage:
+This section lists all possible __SUBACK__ Properties and describes their usage:
 
 [table:suback_props SUBACK properties
 	[[Identifier] [Value type] [Description]]
diff --git a/doc/qbk/reference/properties/SUBSCRIBE_props.qbk b/doc/qbk/reference/properties/subscribe_props.qbk
similarity index 83%
rename from doc/qbk/reference/properties/SUBSCRIBE_props.qbk
rename to doc/qbk/reference/properties/subscribe_props.qbk
index 2c222be..5889c7c 100644
--- a/doc/qbk/reference/properties/SUBSCRIBE_props.qbk
+++ b/doc/qbk/reference/properties/subscribe_props.qbk
@@ -5,12 +5,12 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:async_mqtt5__SUBSCRIBE_props SUBSCRIBE properties]
-The last field in the Variable header of SUBSCRIBE packet is a set of Properties.
+[section:async_mqtt5__subscribe_props SUBSCRIBE properties]
+The last field in the Variable header of __SUBSCRIBE__ packet is a set of Properties.
 A set contains a Property Length followed by the Properties.
 A Property consists of an Identifier and a value.
 
-This section lists all possible SUBSCRIBE Properties and describes their usage:
+This section lists all possible __SUBSCRIBE__ Properties and describes their usage:
 
 [table:subscribe_props SUBSCRIBE properties
 	[[Identifier] [Value type] [Description]]
diff --git a/doc/qbk/reference/properties/UNSUBACK_props.qbk b/doc/qbk/reference/properties/unsuback_props.qbk
similarity index 82%
rename from doc/qbk/reference/properties/UNSUBACK_props.qbk
rename to doc/qbk/reference/properties/unsuback_props.qbk
index 62b80eb..4799065 100644
--- a/doc/qbk/reference/properties/UNSUBACK_props.qbk
+++ b/doc/qbk/reference/properties/unsuback_props.qbk
@@ -5,12 +5,12 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:async_mqtt5__UNSUBACK_props UNSUBACK properties]
-The last field in the Variable header of UNSUBACK packet is a set of Properties.
+[section:async_mqtt5__unsuback_props UNSUBACK properties]
+The last field in the Variable header of __UNSUBACK__ packet is a set of Properties.
 A set contains a Property Length followed by the Properties.
 A Property consists of an Identifier and a value.
 
-This section lists all possible UNSUBACK Properties and describes their usage:
+This section lists all possible __UNSUBACK__ Properties and describes their usage:
 
 [table:unsuback_props UNSUBACK properties
 	[[Identifier] [Value type] [Description]]
diff --git a/doc/qbk/reference/properties/UNSUBSCRIBE_props.qbk b/doc/qbk/reference/properties/unsubscribe_props.qbk
similarity index 82%
rename from doc/qbk/reference/properties/UNSUBSCRIBE_props.qbk
rename to doc/qbk/reference/properties/unsubscribe_props.qbk
index 4b816d7..3a8ae82 100644
--- a/doc/qbk/reference/properties/UNSUBSCRIBE_props.qbk
+++ b/doc/qbk/reference/properties/unsubscribe_props.qbk
@@ -5,12 +5,12 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:async_mqtt5__UNSUBSCRIBE_props UNSUBSCRIBE properties]
-The last field in the Variable header of UNSUBSCRIBE packet is a set of Properties.
+[section:async_mqtt5__unsubscribe_props UNSUBSCRIBE properties]
+The last field in the Variable header of __UNSUBSCRIBE__ packet is a set of Properties.
 A set contains a Property Length followed by the Properties.
 A Property consists of an Identifier and a value.
 
-This section lists all possible UNSUBSCRIBE Properties and describes their usage:
+This section lists all possible __UNSUBSCRIBE__ Properties and describes their usage:
 
 [table:unsubscribe_props UNSUBSCRIBE properties
 	[[Identifier] [Value type] [Description]]
diff --git a/doc/qbk/reference/properties/Will_props.qbk b/doc/qbk/reference/properties/will_props.qbk
similarity index 87%
rename from doc/qbk/reference/properties/Will_props.qbk
rename to doc/qbk/reference/properties/will_props.qbk
index 57a5ffa..10c0493 100644
--- a/doc/qbk/reference/properties/Will_props.qbk
+++ b/doc/qbk/reference/properties/will_props.qbk
@@ -5,12 +5,13 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:async_mqtt5__Will_props [reflink2 will Will] properties]
-The Will Properties consist of the properties that determine when to publish the Will Message and the Application Message properties to be sent with the Will Message.
+[section:async_mqtt5__will_props Will properties]
+The Will Properties consist of the properties that determine when to publish the [reflink2 will Will] Message 
+and the Application Message properties to be sent with the [reflink2 will Will] Message.
 The Will Properties consists of a Property Length and the Properties.
 A Property consists of an Identifier and a value.
 
-This section lists all possible Will Properties and describes their usage:
+This section lists all possible [reflink2 will Will] Properties and describes their usage:
 
 [table:will_props Will properties
 	[[Identifier] [Value type] [Description]]
diff --git a/doc/qbk/reference/quickref.xml b/doc/qbk/reference/quickref.xml
index dc3c4ef..5de853a 100644
--- a/doc/qbk/reference/quickref.xml
+++ b/doc/qbk/reference/quickref.xml
@@ -56,20 +56,20 @@
       <entry valign="top">
         <bridgehead renderas="sect3">Properties</bridgehead>
         <simplelist type="vert" columns="1">
-          <member><link linkend="async_mqtt5.ref.async_mqtt5__Will_props">Will properties</link></member>
-          <member><link linkend="async_mqtt5.ref.async_mqtt5__CONNECT_props">CONNECT properties</link></member>
-          <member><link linkend="async_mqtt5.ref.async_mqtt5__CONNACK_props">CONNACK properties</link></member>
-          <member><link linkend="async_mqtt5.ref.async_mqtt5__PUBLISH_props">PUBLISH properties</link></member>
-          <member><link linkend="async_mqtt5.ref.async_mqtt5__PUBACK_props">PUBACK properties</link></member>
-          <member><link linkend="async_mqtt5.ref.async_mqtt5__PUBREC_props">PUBREC properties</link></member>
-          <member><link linkend="async_mqtt5.ref.async_mqtt5__PUBREL_props">PUBREL properties</link></member>
-          <member><link linkend="async_mqtt5.ref.async_mqtt5__PUBCOMP_props">PUBCOMP properties</link></member>
-          <member><link linkend="async_mqtt5.ref.async_mqtt5__SUBSCRIBE_props">SUBSCRIBE properties</link></member>
-          <member><link linkend="async_mqtt5.ref.async_mqtt5__SUBACK_props">SUBACK properties</link></member>
-          <member><link linkend="async_mqtt5.ref.async_mqtt5__UNSUBSCRIBE_props">UNSUBSCRIBE properties</link></member>
-          <member><link linkend="async_mqtt5.ref.async_mqtt5__UNSUBACK_props">UNSUBACK properties</link></member>
-          <member><link linkend="async_mqtt5.ref.async_mqtt5__DISCONNECT_props">DISCONNECT properties</link></member>
-          <member><link linkend="async_mqtt5.ref.async_mqtt5__AUTH_props">AUTH properties</link></member>
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__will_props">will_props</link></member>
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__connect_props">connect_props</link></member>
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__connack_props">connack_props</link></member>
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__publish_props">publish_props</link></member>
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__puback_props">puback_props</link></member>
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__pubrec_props">pubrec_props</link></member>
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__pubrel_props">pubrel_props</link></member>
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__pubcomp_props">pubcomp_props</link></member>
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__subscribe_props">subscribe_props</link></member>
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__suback_props">suback_props</link></member>
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__unsubscribe_props">unsubscribe_props</link></member>
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__unsuback_props">unsuback_props</link></member>
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__disconnect_props">disconnect_props</link></member>
+          <member><link linkend="async_mqtt5.ref.async_mqtt5__auth_props">auth_props</link></member>
         </simplelist>
       </entry>
     </row></tbody>
diff --git a/doc/qbk/reference/reason_codes/Reason_codes.qbk b/doc/qbk/reference/reason_codes/Reason_codes.qbk
index 11d908d..73cd0d3 100644
--- a/doc/qbk/reference/reason_codes/Reason_codes.qbk
+++ b/doc/qbk/reference/reason_codes/Reason_codes.qbk
@@ -8,7 +8,7 @@
 
 [section:async_mqtt5__Reason_codes Reason codes]
 
-This section lists all possible reason codes that can be sent in a
+This section lists all possible [reflink2 reason_code reason codes] that can be sent in a
 MQTT Control Packet.
 
 [xinclude rcref.xml]
diff --git a/doc/xsl/custom-overrides.xsl b/doc/xsl/custom-overrides.xsl
index d78f541..643f045 100644
--- a/doc/xsl/custom-overrides.xsl
+++ b/doc/xsl/custom-overrides.xsl
@@ -28,6 +28,7 @@
   
 
     <xsl:variable name="emphasized-template-parameter-types" select="
+    'CompletionToken',
     'ExecutionContext',
     'StreamType',
     'TlsContext'
diff --git a/include/async_mqtt5/error.hpp b/include/async_mqtt5/error.hpp
index 9fe43c2..2b3d34c 100644
--- a/include/async_mqtt5/error.hpp
+++ b/include/async_mqtt5/error.hpp
@@ -7,18 +7,19 @@
 #include <boost/asio/error.hpp>
 
 namespace async_mqtt5 {
+
 /**
  * \brief A representation of Disconnect Reason Code.
  *
  * \details Represents all Reason Codes that the Client can send to the Server
- * in the DISCONNECT packet as the reason for the disconnection.
+ * in the \__DISCONNECT\__ packet as the reason for the disconnection.
  */
 enum class disconnect_rc_e : std::uint8_t {
-	/** Close the connection normally. Do not send the \ref will Message. */
+	/** Close the connection normally. Do not send the Will Message. */
 	normal_disconnection = 0x00,
 
 	/** The Client wishes to disconnect but requires that
-	 the Server also publishes its \ref will Message. */
+	 the Server also publishes its Will Message. */
 	disconnect_with_will_message = 0x04,
 
 	// TODO: these reason codes should not be available to the user, only the client
@@ -103,11 +104,13 @@ struct client_ec_category : public boost::system::error_category {
 	}
 };
 
+/// Returns the error category associated with \ref client::error.
 inline const client_ec_category& get_error_code_category() {
 	static client_ec_category cat;
 	return cat;
 }
 
+/// Creates an \ref error_code from a \ref client::error.
 inline boost::system::error_code make_error_code(error r) {
 	return { static_cast<int>(r), get_error_code_category() };
 }
@@ -115,6 +118,7 @@ inline boost::system::error_code make_error_code(error r) {
 
 } // end namespace client
 
+/// \cond internal
 namespace reason_codes {
 
 enum class category : uint8_t {
@@ -124,24 +128,26 @@ enum class category : uint8_t {
 	unsuback, auth, disconnect
 };
 
-
 } // end namespace reason_codes
 
+/// \endcond
+
 /**
  * \brief A class holding Reason Code values originating from Control Packets.
  *
  * \details A Reason Code is a one byte unsigned value that indicates the result of an operation.
- *  Reason Codes less than 0x80 indicate successful completion of an operation.
- *  The normal Reason Code for success is 0.
- *  Reason Code values of 0x80 or greater indicate failure.
- *	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.
+ *	Reason Codes less than 0x80 indicate successful completion of an operation.
+ *	The normal Reason Code for success is 0.
+ *	Reason Code values of 0x80 or greater indicate failure.
+ *	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.
  */
 class reason_code {
 	uint8_t _code;
 	reason_codes::category _category { reason_codes::category::none };
 public:
-/// @cond INTERNAL
+/// \cond INTERNAL
 	constexpr reason_code() : _code(0xff) {}
 
 	constexpr reason_code(uint8_t code, reason_codes::category cat)
@@ -149,7 +155,7 @@ public:
 	{}
 
 	constexpr reason_code(uint8_t code) : _code(code) {}
-/// @endcond 
+/// \endcond 
 
 	/// Copy constructor.
 	reason_code(const reason_code&) = default;
diff --git a/include/async_mqtt5/impl/disconnect_op.hpp b/include/async_mqtt5/impl/disconnect_op.hpp
index 5e32f79..40b290d 100644
--- a/include/async_mqtt5/impl/disconnect_op.hpp
+++ b/include/async_mqtt5/impl/disconnect_op.hpp
@@ -86,6 +86,7 @@ public:
 			ec == asio::error::operation_aborted ||
 			ec == asio::error::no_recovery
 		)
+			// TODO: do we need two different errors here?
 			return complete(ec);
 
 		if (_context.terminal) {
diff --git a/include/async_mqtt5/mqtt_client.hpp b/include/async_mqtt5/mqtt_client.hpp
index ab66d91..d53a1e7 100644
--- a/include/async_mqtt5/mqtt_client.hpp
+++ b/include/async_mqtt5/mqtt_client.hpp
@@ -17,7 +17,7 @@ namespace async_mqtt5 {
 namespace asio = boost::asio;
 
 /**
- * \brief MQTT client used to connect and communicate with a Broker.
+ * \brief \__MQTT\__ client used to connect and communicate with a Broker.
  *
  * \tparam StreamType Type of the underlying transport protocol used to transfer
  * the stream of bytes between the Client and the Broker. The transport must be
@@ -71,7 +71,9 @@ public:
 	 * \param tls_context A context object used in TLS/SLL connection.
 	 *
 	 * \par Precondition
-	 * `std::is_convertible_v<ExecutionContext&, asio::execution_context&>`
+	 * \code
+	 * std::is_convertible_v<ExecutionContext&, asio::execution_context&>
+	 * \endcode
 	 */
 	template <typename ExecutionContext>
 	requires (std::is_convertible_v<ExecutionContext&, asio::execution_context&>)
@@ -103,8 +105,14 @@ public:
 	/**
 	 * \brief Get the context object used in TLS/SSL connection.
 	 *
+	 * \note This function may only be invoked
+	 * when the template parameter \__TlsContext\__ was configured
+	 * with non-default type during the creation of a \ref mqtt_client.
+	 *
 	 * \par Precondition
-	 * `!std::is_same_v<TlsContext, std::monostate>`.
+	 * \code
+	 * !std::is_same_v<TlsContext, std::monostate>
+	 * \endcode
 	 */
 	decltype(auto) tls_context()
 	requires (!std::is_same_v<TlsContext, std::monostate>) {
@@ -124,10 +132,12 @@ public:
 
 	// TODO: channel cancel
 	/**
-	 * \brief Cancel all asynchronous operations.
+	 * \brief Cancel all asynchronous operations. This function has terminal effects.
 	 *
 	 * \details All outstanding operations will complete
 	 * with `boost::asio::error::operation_aborted`.
+	 *
+	 * \note The Client cannot be used before calling \ref mqtt_client::run again.
 	 */
 	void cancel() {
 		get_executor().execute([svc_ptr = _svc_ptr]() {
@@ -167,15 +177,25 @@ public:
 	/**
 	 * \brief Assign a list of Brokers that the Client will attempt to connect to.
 	 *
+	 * \details The Client will cycle through the list of hosts,
+	 * attempting to establish a connection with each
+	 * until it successfully establishes a connection.
+	 *
 	 * \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.
 	 *
-	 * \details Examples of a valid hosts string:\n
-	 *		- broker1:1883, broker2, broker3:1883\n
-	 *		- broker1
+	 *
+	 * \par Example
+	 * Some valid hosts string:
+	 *
+	 * \code
+	 *		std::string valid_hosts_1 = "broker1:1883, broker2, broker3:1883";
+	 *		std::string valid_hosts_2 = "broker1";
+	 * \endcode
+	 *
 	 */
 	mqtt_client& brokers(std::string hosts, uint16_t default_port = 1883) {
 		_svc_ptr->brokers(std::move(hosts), default_port);
@@ -183,9 +203,8 @@ public:
 	}
 
 
-	// TODO: doc props
 	/**
-	 * \brief Send a PUBLISH packet to Broker to transport an
+	 * \brief Send a \__PUBLISH\__ packet to Broker to transport an
 	 * Application Message.
 	 *
 	 * \tparam qos_type The \ref qos_e level of assurance for delivery.
@@ -193,35 +212,35 @@ public:
 	 * Payload data is published.
 	 * \param payload The Application Message that is being published.
 	 * \param retain The \ref retain_e flag.
-	 * \param props PUBLISH properties. 
+	 * \param props An instance of \__PUBLISH_PROPS\__. 
 	 * \param token Completion token that will be used to produce a
 	 * completion handler, which will be called when the operation completed.
 	 *
-	 * \par Completion signature
-	 * The completion signature for this operation depends on the \ref qos_e specified:\n
+	 * \par Handler signature
+	 * The handler signature for this operation depends on the \ref qos_e specified:\n
 	 *
 	 *	- `qos_e::at_most_once`:
 	 *		\code
 	 *			void (
-	 *				boost::system::error_code	// Result of operation
+	 *				__ERROR_CODE__	// Result of operation
 	 *			)
 	 *		\endcode
 	 *
 	 *	- `qos_e::at_least_once`:
 	 *		\code
 	 *			void (
-	 *				boost::system::error_code,	// Result of operation.
-	 *				async_mqtt5::reason_code,	// Reason Code received from Broker.
-	 *				puback_props	// Properties received in the PUBACK packet.
+	 *				__ERROR_CODE__,	// Result of operation.
+	 *				__REASON_CODE__,	// Reason Code received from Broker.
+	 *				__PUBACK_PROPS__	// Properties received in the PUBACK packet.
 	 *			)
 	 *		\endcode
 	 *
 	 *	- `qos_e::exactly_once`:
 	 *		\code
 	 *			void (
-	 *				boost::system::error_code,	// Result of operation.
-	 *				async_mqtt5::reason_code,	// Reason Code received from Broker.
-	 *				pubcomp_props	// Properties received in the PUBCOMP packet.
+	 *				__ERROR_CODE__,	// Result of operation.
+	 *				__REASON_CODE__,	// Reason Code received from Broker.
+	 *				__PUBCOMP_PROPS__	// Properties received in the PUBCOMP packet.
 	 *			)
 	 *		\endcode
 	 *
@@ -264,28 +283,28 @@ public:
 
 	// TODO: perhaps there is a way to not copy documentation (\copybrief, \copydetails)
 	/**
-	 * \brief Send a SUBSCRIBE packet to Broker to create a subscription
+	 * \brief Send a \__SUBSCRIBE\__ packet to Broker to create a subscription
 	 * to one or more Topics of interest.
 	 *
 	 * \details After the subscription has been established, the Broker will send
 	 * PUBLISH packets to the Client to forward Application Messages that were published
-	 * to Topics that the Client subscribed to. The PUBLISH packets can be received
+	 * to Topics that the Client subscribed to. The \__PUBLISH\__ packets can be received
 	 * with \ref mqtt_client::async_receive function.
 	 *
 	 * \param topics A list of \ref subscribe_topic of interest.
-	 * \param props SUBSCRIBE properties.
+	 * \param props An instance of \__SUBSCRIBE_PROPS\__.
 	 * \param token Completion token that will be used to produce a
 	 * completion handler, which will be called when the operation completed.
 	 *
-	 * \par Completion signature
-	 * The completion signature for this operation:
+	 * \par Handler signature
+	 * The handler signature for this operation:
 	 *	\code
 	 *		void (
-	 *			boost::system::error_code,	// Result of operation.
-	 *			std::vector<reason_code>,	// Vector of Reason Codes indicating
-	 *										// the subscription result for each Topic
-	 *										// in the SUBSCRIBE packet.
-	 *			suback_props,	// Properties received in the SUBACK packet.
+	 *			__ERROR_CODE__,	// Result of operation.
+	 *			std::vector<__REASON_CODE__>,	// Vector of Reason Codes indicating
+	 *													// the subscription result for each Topic
+	 *													// in the SUBSCRIBE packet.
+	 *			__SUBACK_PROPS__,	// Properties received in the SUBACK packet.
 	 *		)
 	 *	\endcode
 	 *
@@ -319,28 +338,28 @@ public:
 	}
 
 	/**
-	 * \brief Send a SUBSCRIBE packet to Broker to create a subscription
+	 * \brief Send a \__SUBSCRIBE\__ packet to Broker to create a subscription
 	 * to one Topics of interest.
 	 *
 	 * \details After the subscription has been established, the Broker will send
-	 * PUBLISH packets to the Client to forward Application Messages that were published
-	 * to Topics that the Client subscribed to. The PUBLISH packets can be received
+	 * \__PUBLISH\__ packets to the Client to forward Application Messages that were published
+	 * to Topics that the Client subscribed to. The \__PUBLISH\__ packets can be received
 	 * with \ref mqtt_client::async_receive function.
 	 *
 	 * \param topic A \ref subscribe_topic of interest.
-	 * \param props SUBSCRIBE properties.
+	 * \param props An instance of \__SUBSCRIBE_PROPS\__.
 	 * \param token Completion token that will be used to produce a
 	 * completion handler, which will be called when the operation completed.
 	 *
-	 * \par Completion signature
-	 * The completion signature for this operation:
+	 * \par Handler signature
+	 * The handler signature for this operation:
 	 *	\code
 	 *		void (
-	 *			boost::system::error_code,	// Result of operation.
-	 *			std::vector<reason_code>,	// Vector of Reason Codes containing the
-	 *										// single subscription result for the Topic
-	 *										// in the SUBSCRIBE packet.
-	 *			suback_props,	// Properties received in the SUBACK packet.
+	 *			__ERROR_CODE__,	// Result of operation.
+	 *			std::vector<__REASON_CODE__>,	// Vector of Reason Codes containing the
+	 *													// single subscription result for the Topic
+	 *													// in the SUBSCRIBE packet.
+	 *			__SUBACK_PROPS__,	// Properties received in the SUBACK packet.
 	 *		)
 	 *	\endcode
 	 *
@@ -363,27 +382,27 @@ public:
 
 
 	/**
-	 * \brief Send an UNSUBSCRIBE packet to Broker to unsubscribe from one
+	 * \brief Send an \__UNSUBSCRIBE\__ packet to Broker to unsubscribe from one
 	 * or more Topics.
 	 *
-	 * \note The Client MAY receive PUBLISH packets with Application
+	 * \note The Client MAY receive \__PUBLISH\__ packets with Application
 	 * Messages from Topics the Client just unsubscribed to if
 	 * they were buffered for delivery on the Broker side beforehand.
 	 *
 	 * \param topics List of Topics to unsubscribe from.
-	 * \param props UNSUBSCRIBE properties.
+	 * \param props An instance of \__UNSUBSCRIBE_PROPS\__.
 	 * \param token Completion token that will be used to produce a
 	 * completion handler, which will be called when the operation completed.
 	 *
-	 * \par Completion signature
-	 * The completion signature for this operation:
+	 * \par Handler signature
+	 * The handler signature for this operation:
 	 *	\code
 	 *		void (
-	 *			boost::system::error_code, // Result of operation.
-	 *			std::vector<reason_code>,	// Vector of Reason Codes indicating
-	 *										// the result of unsubscribe operation
-	 *										// for each Topic in the UNSUBSCRIBE packet.
-	 *			unsuback_props, // Properties received in the UNSUBACK packet.
+	 *			__ERROR_CODE__, // Result of operation.
+	 *			std::vector<__REASON_CODE__>,	// Vector of Reason Codes indicating
+	 *													// the result of unsubscribe operation
+	 *													// for each Topic in the UNSUBSCRIBE packet.
+	 *			__UNSUBACK_PROPS__, // Properties received in the UNSUBACK packet.
 	 *		)
 	 *	\endcode
 	 *
@@ -417,27 +436,27 @@ public:
 	}
 
 	/**
-	 * \brief Send an UNSUBSCRIBE packet to Broker to unsubscribe
+	 * \brief Send an \__UNSUBSCRIBE\__ packet to Broker to unsubscribe
 	 * from one Topic.
 	 *
-	 * \note The Client MAY receive PUBLISH packets with Application
+	 * \note The Client MAY receive \__PUBLISH\__ packets with Application
 	 * Messages from Topics the Client just unsubscribed to if
 	 * they were buffered for delivery on the Broker side beforehand.
 	 *
 	 * \param topic Topic to unsubscribe from.
-	 * \param props UNSUBSCRIBE properties.
+	 * \param props An instance of \__UNSUBSCRIBE_PROPS\__.
 	 * \param token Completion token that will be used to produce a
 	 * completion handler, which will be called when the operation completed.
 	 *
-	 * \par Completion signature
-	 * The completion signature for this operation:
+	 * \par Handler signature
+	 * The handler signature for this operation:
 	 *	\code
 	 *		void (
-	 *			boost::system::error_code, // Result of operation.
-	 *			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.
+	 *			__ERROR_CODE__, // Result of operation.
+	 *			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.
 	 *		)
 	 *	\endcode
 	 *
@@ -458,11 +477,13 @@ public:
 		);
 	}
 
+
+	// TODO: cancel the channel!
 	/**
 	 * \brief Asynchronously receive an Application Message.
 	 *
 	 * \details The Client will receive and complete deliveries for all the
-	 * PUBLISH packets received from the Broker throughout its lifetime.
+	 * \__PUBLISH\__ packets received from the Broker throughout its lifetime.
 	 * The Client will store them internally in order they were delivered.
 	 * Calling this function will attempt to receive an Application Message
 	 * from internal storage.
@@ -473,14 +494,14 @@ public:
 	 * \param token Completion token that will be used to produce a
 	 * completion handler, which will be called when the operation completed.
 	 *
-	 * \par Completion signature
-	 * The completion signature for this operation:
+	 * \par Handler signature
+	 * The handler signature for this operation:
 	 *	\code
 	 *		void (
-	 *			boost::system::error_code, // Result of operation.
+	 *			__ERROR_CODE__, // Result of operation.
 	 *			std::string,	// Topic, the origin of the Application Message.
 	 *			std::string,	// Payload, the content of the Application Message.
-	 *			publish_props, // Properties received in the PUBLISH packet.
+	 *			__PUBLISH_PROPS__, // Properties received in the PUBLISH packet.
 	 *		)
 	 *	\endcode
 	 *
@@ -498,24 +519,24 @@ public:
 	}
 
 	/**
-	 * \brief Disconnect the Client.
+	 * \brief Disconnect the Client. This function has terminal effects.
 	 *
-	 * \details Send a DISCONNECT packet to the Broker with a Reason Code
+	 * \details Send a \__DISCONNECT\__ packet to the Broker with a Reason Code
 	 * describing the reason for disconnection.
 	 *
-	 * \note This function has terminal effects and will close the Client.
+	 * \note This function will close the Client. See \ref mqtt_client::cancel.
 	 *
 	 * \param reason_code Reason Code to notify
 	 * the Broker of the reason for disconnection.
-	 * \param props DISCONNECT properties.
+	 * \param props An instance of \__DISCONNECT_PROPS\__.
 	 * \param token Completion token that will be used to produce a
 	 * completion handler, which will be called when the operation completed.
 	 *
-	 * \par Completion signature
-	 * The completion signature for this operation:
+	 * \par Handler signature
+	 * The handler signature for this operation:
 	 *	\code
 	 *		void (
-	 *			boost::system::error_code // Result of operation.
+	 *			__ERROR_CODE__ // Result of operation.
 	 *		)
 	 *	\endcode
 	 *
@@ -537,22 +558,22 @@ public:
 	}
 
 	/**
-	 * \brief Disconnect the Client.
+	 * \brief Disconnect the Client. This function has terminal effects.
 	 *
-	 * \details Send a DISCONNECT packet to the Broker with a Reason Code
+	 * \details Send a \__DISCONNECT\__ packet to the Broker with a Reason Code
 	 * \ref reason_codes::normal_disconnection describing
 	 * the reason for disconnection.
 	 *
-	 * \note This function has terminal effects and will close the Client.
+	 * \note This function will close the Client. See \ref mqtt_client::cancel.
 	 *
 	 * \param token Completion token that will be used to produce a
 	 * completion handler, which will be called when the operation completed.
 	 *
-	 * \par Completion signature
-	 * The completion signature for this operation:
+	 * \par Handler signature
+	 * The handler signature for this operation:
 	 *	\code
 	 *		void (
-	 *			boost::system::error_code // Result of operation.
+	 *			__ERROR_CODE__ // Result of operation.
 	 *		)
 	 *	\endcode
 	 *
diff --git a/include/async_mqtt5/types.hpp b/include/async_mqtt5/types.hpp
index f5b408d..8e4beb3 100644
--- a/include/async_mqtt5/types.hpp
+++ b/include/async_mqtt5/types.hpp
@@ -22,10 +22,11 @@ struct authority_path {
 };
 
 /**
- * \brief Represents the Quality of Service (QoS) property of the PUBLISH packets.
+ * \brief Represents the Quality of Service (\__QOS__\)
+ * property of the \__PUBLISH\__ packets.
  *
- * \details Determines how the PUBLISH packets are delivered from the sender
- * to the receiver.
+ * \details Determines how the \__PUBLISH\__ packets are delivered
+ * from the sender to the receiver.
  */
 enum class qos_e : std::uint8_t {
 	/** The message arrives at the receiver either once or not at all. */
@@ -40,7 +41,7 @@ enum class qos_e : std::uint8_t {
 };
 
 /**
- * \brief Represents the RETAIN flag in the PUBLISH packets.
+ * \brief Represents the RETAIN flag in the \__PUBLISH\__ packets.
  *
  * \details This flag informs the Server about whether or not it should
  * store the current message.
@@ -62,12 +63,11 @@ enum class dup_e : std::uint8_t {
 
 
 /**
- * \brief Represents the Options associated with each Subscription.
+ * \brief Represents the \__SUBSCRIBE_OPTIONS\__ associated with each Subscription.
  */
 struct subscribe_options {
 
 	/**
-	 *
 	 * \brief Representation of the No Local Subscribe Option.
 	 *
 	 * \details A Subscribe Option indicating whether or not Application Messages
@@ -190,6 +190,8 @@ reason codes:
 
 */
 
+/// \cond
+
 class connect_props : public prop::properties<
 	prop::session_expiry_interval,
 	prop::receive_maximum,
@@ -299,6 +301,7 @@ class will_props : public prop::properties<
 	prop::user_property
 >{};
 
+/// \endcond
 
 /**
  * \brief Represents the Will Message.