From 2f1f910552a612b85fb16bc47046b457ff2691bb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Korina=20=C5=A0imi=C4=8Devi=C4=87?= <korina@mireo.local>
Date: Thu, 26 Oct 2023 12:31:02 +0200
Subject: [PATCH] [mqtt-client] some doc fixes

Summary:
related to T12804

- b2 rebuilds when documented .hpp files are changed

- some text changes

- some link fixes

Reviewers: ivica

Reviewed By: ivica

Subscribers: miljen

Differential Revision: https://repo.mireo.local/D26240
---
 doc/Jamfile                          |   5 +
 doc/qbk/00_main.qbk                  |  10 +-
 doc/qbk/reference/Error_handling.qbk |   2 +-
 doc/reference.dox                    |   2 +-
 doc/reference.xsl                    | 204 ++++++++++++++++++++++-----
 include/async_mqtt5/mqtt_client.hpp  |  35 ++---
 include/async_mqtt5/types.hpp        |  10 +-
 7 files changed, 206 insertions(+), 62 deletions(-)

diff --git a/doc/Jamfile b/doc/Jamfile
index e4c8638..042a45d 100644
--- a/doc/Jamfile
+++ b/doc/Jamfile
@@ -29,6 +29,11 @@ import boostbook ;
 make xml/index.xml
 	:
 		reference.dox
+		
+		# additional dependencies
+		../include/async_mqtt5/error.hpp
+		../include/async_mqtt5/types.hpp
+		../include/async_mqtt5/mqtt_client.hpp
 	:
 		@call-doxygen
 	;
diff --git a/doc/qbk/00_main.qbk b/doc/qbk/00_main.qbk
index 9749164..2560fc6 100644
--- a/doc/qbk/00_main.qbk
+++ b/doc/qbk/00_main.qbk
@@ -15,7 +15,7 @@
 
 [template nochunk[] [block '''<?dbhtml stop-chunking?>''']]
 [template mdash[] '''&mdash; ''']
-[template hr[] [br]'''<phrase role="silver">'''[mdash]'''</phrase>'''[br]]
+[template hr[] '''<phrase role="silver">'''[mdash]'''</phrase>''']
 [template include_file[path][^<'''<ulink url="GITHUB_LINK">'''[path]'''</ulink>'''>]]
 [template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>''']
 [template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>''']
@@ -31,10 +31,10 @@
 
 [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]]]
-[def __TlsContext__ [reflink2 TlsContext ['TlsContext]]]
+[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]]
+[def __TlsContext__ [reflink2 TlsContext TlsContext]]
 
 [def __Boost__ [@https://www.boost.org/ Boost]]
 [def __Asio__ [@boost:/libs/asio/index.html Boost.Asio]]
diff --git a/doc/qbk/reference/Error_handling.qbk b/doc/qbk/reference/Error_handling.qbk
index cb056bd..bd3b814 100644
--- a/doc/qbk/reference/Error_handling.qbk
+++ b/doc/qbk/reference/Error_handling.qbk
@@ -36,7 +36,7 @@ may complete with, along with the reasons for their occurrence.
 		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.
+		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.
 	]]
diff --git a/doc/reference.dox b/doc/reference.dox
index b70c961..a524653 100644
--- a/doc/reference.dox
+++ b/doc/reference.dox
@@ -32,7 +32,7 @@ SUBGROUPING            = YES
 # Build related configuration options
 #---------------------------------------------------------------------------
 EXTRACT_ALL            = YES
-EXTRACT_PRIVATE        = YES
+EXTRACT_PRIVATE        = NO
 EXTRACT_STATIC         = YES
 EXTRACT_LOCAL_CLASSES  = NO
 EXTRACT_LOCAL_METHODS  = NO
diff --git a/doc/reference.xsl b/doc/reference.xsl
index da161b7..69a29c6 100644
--- a/doc/reference.xsl
+++ b/doc/reference.xsl
@@ -420,14 +420,18 @@
       <xsl:apply-templates mode="markup"/>
     </xsl:when>
     <xsl:when test="@kind='see'">
+[heading See More]
+      <xsl:apply-templates mode="markup"/>
     </xsl:when>
     <xsl:when test="@kind='note'">
-[heading Remarks]
+[note
       <xsl:apply-templates mode="markup"/>
+]
     </xsl:when>
     <xsl:when test="@kind='attention'">
-[heading Attention]
+[important
       <xsl:apply-templates mode="markup"/>
+]
     </xsl:when>
     <xsl:when test="@kind='par'">
       <xsl:if test="not(starts-with(title, 'Concepts:'))">
@@ -634,6 +638,13 @@
       <xsl:value-of name="text" select="$ref-name"/>
       <xsl:text>`]</xsl:text>
     </xsl:when>
+    <xsl:when test="contains(@refid, 'async__mqtt5_1_1client') and count($memberdefs) = 0">
+      <xsl:text>
+      [link async_mqtt5.ref.client.error</xsl:text>
+      <xsl:text> `</xsl:text>
+      <xsl:value-of select='text()'/>
+      <xsl:text>`]</xsl:text>
+    </xsl:when>
     <xsl:otherwise>
       <xsl:text>`</xsl:text>
       <xsl:value-of select="."/>
@@ -847,14 +858,14 @@
       <xsl:if test="starts-with($name, '~')"> [destructor]</xsl:if>
       <xsl:if test="@static='yes'"> [static]</xsl:if>
       <xsl:text>]
-    [</xsl:text><xsl:value-of select="briefdescription"/>
+    [</xsl:text><xsl:apply-templates select="briefdescription" mode="markup"/>
   </xsl:if>
   <xsl:if test="not($overload-position = 1) and not(briefdescription = preceding-sibling::*/briefdescription)">
     <xsl:value-of select="$newline"/>
     <xsl:text>     [hr]</xsl:text>
     <xsl:value-of select="$newline"/>
     <xsl:text>     </xsl:text>
-    <xsl:value-of select="briefdescription"/>
+    <xsl:apply-templates select="briefdescription" mode="markup"/>
   </xsl:if>
   <xsl:if test="$overload-position = $overload-count">
   <xsl:text>]
@@ -901,14 +912,14 @@
       <xsl:if test="starts-with($name, '~')"> [destructor]</xsl:if>
       <xsl:if test="@static='yes'"> [static]</xsl:if>
       <xsl:text>]
-    [</xsl:text><xsl:value-of select="briefdescription"/>
+    [</xsl:text><xsl:apply-templates select="briefdescription" mode="markup"/>
   </xsl:if>
   <xsl:if test="not($overload-position = 1) and not(briefdescription = preceding-sibling::*/briefdescription)">
     <xsl:value-of select="$newline"/>
     <xsl:text>     [hr]</xsl:text>
     <xsl:value-of select="$newline"/>
     <xsl:text>     </xsl:text>
-    <xsl:value-of select="briefdescription"/>
+    <xsl:apply-templates select="briefdescription" mode="markup"/>
   </xsl:if>
   <xsl:if test="$overload-position = $overload-count">
   <xsl:text>]
@@ -956,14 +967,14 @@
       <xsl:if test="starts-with($name, '~')"> [destructor]</xsl:if>
       <xsl:if test="@static='yes'"> [static]</xsl:if>
       <xsl:text>]
-    [</xsl:text><xsl:value-of select="briefdescription"/>
+    [</xsl:text><xsl:apply-templates select="briefdescription" mode="markup"/>
   </xsl:if>
   <xsl:if test="not($overload-position = 1) and not(briefdescription = preceding-sibling::*/briefdescription)">
     <xsl:value-of select="$newline"/>
     <xsl:text>     [hr]</xsl:text>
     <xsl:value-of select="$newline"/>
     <xsl:text>     </xsl:text>
-    <xsl:value-of select="briefdescription"/>
+    <xsl:apply-templates select="briefdescription" mode="markup"/>
   </xsl:if>
   <xsl:if test="$overload-position = $overload-count">
   <xsl:text>]
@@ -985,7 +996,7 @@
     [[link async_mqtt5.ref.<xsl:value-of select="$class-id"/>.<xsl:value-of select="name"/>
       <xsl:text> </xsl:text>[*<xsl:value-of select="name"/><xsl:text>]]</xsl:text>
       <xsl:if test="@static='yes'"> [static]</xsl:if>]
-    [<xsl:value-of select="briefdescription"/>]
+    [<xsl:apply-templates select="briefdescription" mode="markup"/>]
   ]
 </xsl:for-each>
 ]
@@ -1197,12 +1208,18 @@
     <xsl:with-param name="name" select="type"/>
   </xsl:call-template>
  </xsl:variable>
+<xsl:variable name="impl-keyword">
+ <xsl:call-template name="implementation-keyword">
+   <xsl:with-param name="argsstring" select="argsstring"/>
+ </xsl:call-template>
+</xsl:variable>
  <xsl:if test="string-length($stripped-type) &gt; 0">
  <xsl:value-of select="$stripped-type"/><xsl:text> </xsl:text>
 </xsl:if>``[link async_mqtt5.ref.<xsl:value-of select="$class-id"/>.<xsl:value-of
  select="$id"/>.overload<xsl:value-of select="position()"/><xsl:text> </xsl:text><xsl:value-of
  select="name"/>]``(<xsl:apply-templates select="param"
- mode="class-detail"/>)<xsl:if test="@const='yes'"> const</xsl:if>;
+ mode="class-detail"/><xsl:if test="count(param) &gt; 0"><xsl:text>
+  </xsl:text></xsl:if>)<xsl:if test="@const='yes'"> const</xsl:if><xsl:value-of select="$impl-keyword"/>;
 <xsl:text>  ``  [''''&amp;raquo;'''</xsl:text>
 <xsl:text> [link async_mqtt5.ref.</xsl:text>
 <xsl:value-of select="$class-id"/>.<xsl:value-of
@@ -1261,7 +1278,9 @@
     </xsl:when>
   </xsl:choose>
 
+<xsl:if test="count(detaileddescription/*) &gt; 0">
 [heading Description]
+</xsl:if>
 <xsl:text>
 </xsl:text><xsl:apply-templates select="detaileddescription" mode="markup"/>
 
@@ -1361,12 +1380,23 @@
 [table
   [[Name] [Description]]
 <xsl:for-each select="enumvalue">
-  [[<xsl:value-of select="name"/>][<xsl:value-of select="detaileddescription"/>]]
+  [[<xsl:value-of select="name"/>][<xsl:apply-templates select="detaileddescription" mode="markup"/>]]
 </xsl:for-each>
 ]
 </xsl:if>
 </xsl:template>
 
+<xsl:template name="implementation-keyword">
+<xsl:param name="argsstring"/>
+  <xsl:choose>
+    <xsl:when test="contains($argsstring, 'delete')">
+      <xsl:text> = delete</xsl:text>
+    </xsl:when>
+    <xsl:when test="contains($argsstring, 'default')">
+      <xsl:text> = default</xsl:text>
+    </xsl:when>
+  </xsl:choose>
+</xsl:template>
 
 <xsl:template name="function">
 <xsl:text>
@@ -1387,42 +1417,148 @@
    <xsl:with-param name="name" select="type"/>
  </xsl:call-template>
 </xsl:variable>
+<xsl:variable name="impl-keyword">
+ <xsl:call-template name="implementation-keyword">
+   <xsl:with-param name="argsstring" select="argsstring"/>
+ </xsl:call-template>
+</xsl:variable>
 <xsl:text>  </xsl:text><xsl:if test="@static='yes'">static </xsl:if><xsl:if 
  test="@virt='virtual'">virtual </xsl:if><xsl:if
  test="string-length($stripped-type) &gt; 0"><xsl:value-of select="$stripped-type"/><xsl:text> </xsl:text></xsl:if>
 <xsl:value-of select="name"/>(<xsl:apply-templates select="param"
- mode="class-detail"/>)<xsl:if test="@const='yes'"> const</xsl:if>;
+ mode="class-detail"/><xsl:if test="count(param) &gt; 0"><xsl:text>
+  </xsl:text></xsl:if>)<xsl:if test="@const='yes'"> const</xsl:if><xsl:value-of select="$impl-keyword"/>;
 </xsl:template>
 
 
 <xsl:template match="templateparamlist" mode="class-detail">
-<xsl:text>  </xsl:text>template&lt;<xsl:apply-templates select="param" mode="class-detail-template"/>&gt;
+<xsl:text>  </xsl:text>template &lt;<xsl:apply-templates select="param" mode="class-detail-template"/>
+<xsl:text>
+  </xsl:text>&gt;
 </xsl:template>
 
+<xsl:template name="mqtt-property">
+<xsl:param name="qualified-name"/>
+<xsl:variable name="property-name">
+  <xsl:choose>
+    <xsl:when test="contains($qualified-name, 'will_props')">will_props</xsl:when>
+    <!-- disconnect props must be above connect props -->
+    <xsl:when test="contains($qualified-name, 'disconnect_props')">disconnect_props</xsl:when>
+    <xsl:when test="contains($qualified-name, 'connect_props')">connect_props</xsl:when>
+    <xsl:when test="contains($qualified-name, 'connack_props')">connack_props</xsl:when>
+    <xsl:when test="contains($qualified-name, 'publish_props')">publish_props</xsl:when>
+    <xsl:when test="contains($qualified-name, 'puback_props')">puback_props</xsl:when>
+    <xsl:when test="contains($qualified-name, 'pubrec_props')">pubrec_props</xsl:when>
+    <xsl:when test="contains($qualified-name, 'pubrel_props')">pubrel_props</xsl:when>
+    <xsl:when test="contains($qualified-name, 'pubcomp_props')">pubcomp_props</xsl:when>
+    <!-- unsubscribe & unsuback props must be above subscribe & suback props -->
+    <xsl:when test="contains($qualified-name, 'unsubscribe_props')">unsubscribe_props</xsl:when>
+    <xsl:when test="contains($qualified-name, 'unsuback_props')">unsuback_props</xsl:when>
+    <xsl:when test="contains($qualified-name, 'subscribe_props')">subscribe_props</xsl:when>
+    <xsl:when test="contains($qualified-name, 'suback_props')">suback_props</xsl:when>
+    <xsl:when test="contains($qualified-name, 'auth_props')">auth_props</xsl:when>
+    <xsl:otherwise></xsl:otherwise>
+  </xsl:choose>
+</xsl:variable>
+<xsl:if test="string-length($property-name) &gt; 0">
+  <xsl:value-of select="substring-before($qualified-name, $property-name)"/>
+  <xsl:text>``[link async_mqtt5.ref.</xsl:text>
+  <xsl:value-of select="$property-name"/>
+  <xsl:text> </xsl:text>
+  <xsl:value-of select="$property-name"/>
+  <xsl:text>]``</xsl:text>
+  <xsl:value-of select="substring-after($qualified-name, $property-name)"/>
+  <xsl:text> </xsl:text>
+  <xsl:value-of select="declname"/>
+</xsl:if>
+</xsl:template>
+
+<xsl:template name="mqtt-template">
+<xsl:param name="qualified-name"/>
+<xsl:variable name="template-type">
+  <xsl:choose>
+    <xsl:when test="contains($qualified-name, 'CompletionToken')">CompletionToken</xsl:when>
+    <xsl:when test="contains($qualified-name, 'ExecutionContext')">ExecutionContext</xsl:when>
+    <xsl:when test="contains($qualified-name, 'StreamType')">StreamType</xsl:when>
+    <xsl:when test="contains($qualified-name, 'TlsContext')">TlsContext</xsl:when>
+    <xsl:otherwise></xsl:otherwise>
+  </xsl:choose>
+</xsl:variable>
+<xsl:if test="string-length($template-type) &gt; 0">
+  <xsl:value-of select="substring-before($qualified-name, $template-type)"/>
+    <xsl:text>__</xsl:text><xsl:value-of select="$template-type"/><xsl:text>__</xsl:text>
+  <xsl:value-of select="substring-after($qualified-name, $template-type)"/>
+  <xsl:if test="count(declname) &gt; 0">
+    <xsl:text> </xsl:text>
+    <xsl:value-of select="declname"/>
+  </xsl:if>
+</xsl:if>
+</xsl:template>
+
+<xsl:template name="mqtt-ref-id">
+<xsl:param name="ref"/>
+<xsl:choose>
+  <xsl:when test="$ref = 'executor_type'">mqtt_client.<xsl:value-of select="$ref"/></xsl:when>
+  <xsl:when test="$ref = 'error'">client.<xsl:value-of select="$ref"/></xsl:when>
+  <xsl:otherwise><xsl:value-of select="$ref"/></xsl:otherwise>
+</xsl:choose>
+</xsl:template>
+
+<xsl:template name="mqtt-type">
+<xsl:param name="type"/>
+<xsl:choose>
+  <xsl:when test="contains(type, '_props')">
+    <xsl:call-template name="mqtt-property">
+      <xsl:with-param name="qualified-name" select="$type"/>
+    </xsl:call-template>
+  </xsl:when>
+  <xsl:when test="count(type/ref) &gt; 0">
+    <xsl:variable name="typename" select="type/ref"/>
+    <xsl:value-of select="substring-before($type, $typename)"/>
+    <xsl:text>``[link async_mqtt5.ref.</xsl:text>
+    <xsl:call-template name="mqtt-ref-id">
+      <!-- a single type can have either 0 or 1 refs -->
+      <xsl:with-param name="ref" select="type/ref[1]"/>
+    </xsl:call-template>
+    <xsl:text> </xsl:text>
+    <xsl:value-of select="$typename"/>
+    <xsl:text>]``</xsl:text>
+    <xsl:value-of select="substring-after($type, $typename)"/>
+    <xsl:if test="count(declname) &gt; 0">
+      <xsl:text> </xsl:text>
+      <xsl:value-of select="declname"/>
+    </xsl:if>
+  </xsl:when>
+  <!-- unfortunately, there is no better way to differentiate between template types and non-documented types -->
+  <xsl:when test="contains(type, 'CompletionToken') or contains(type, 'ExecutionContext')
+    or contains(type, 'TlsContext') or contains(type, 'StreamType')">
+    <xsl:call-template name="mqtt-template">
+      <xsl:with-param name="qualified-name" select="$type"/>
+    </xsl:call-template>
+  </xsl:when>
+  <xsl:otherwise>
+    <xsl:value-of select="type"/>
+    <xsl:if test="count(declname) &gt; 0">
+      <xsl:text> </xsl:text>
+      <xsl:value-of select="declname"/>
+    </xsl:if>
+  </xsl:otherwise>
+</xsl:choose>
+</xsl:template>
 
 <xsl:template match="param" mode="class-detail-template">
 <xsl:text>
       </xsl:text>
       <xsl:choose>
-        <xsl:when test="type = 'typename CompletionToken'">
-          <xsl:text>typename __CompletionToken__</xsl:text>
-        </xsl:when>
-        <xsl:when test="type = 'typename ExecutionContext'">
-          <xsl:text>typename __ExectionContext__</xsl:text>
-        </xsl:when>
-        <xsl:when test="type = 'typename StreamType'">
-          <xsl:text>typename __StreamType__</xsl:text>
-        </xsl:when>
-        <xsl:when test="type = 'typename TlsContext'">
-          <xsl:text>typename __TlsContext__</xsl:text>
-        </xsl:when>
-        <xsl:when test="count(declname) = 0">
-          <xsl:value-of select="type"/>
+        <xsl:when test="contains(type, 'typename')">
+          <xsl:call-template name="mqtt-template">
+            <xsl:with-param name="qualified-name" select="type"/>
+          </xsl:call-template>
         </xsl:when>
         <xsl:otherwise>
-          <xsl:value-of select="type"/>
-          <xsl:text> </xsl:text>
-          <xsl:value-of select="declname"/>
+          <xsl:call-template name="mqtt-type">
+            <xsl:with-param name="type" select="type"/>
+          </xsl:call-template>
         </xsl:otherwise>
       </xsl:choose>
     <xsl:if test="count(defval) > 0"> = <xsl:value-of select="defval"/>
@@ -1443,11 +1579,13 @@
       <xsl:value-of select="array"/>
     </xsl:when>
     <xsl:otherwise>
-      <xsl:value-of select="type"/>
-      <xsl:text> </xsl:text>
-      <xsl:value-of select="declname"/>
+      <xsl:call-template name="mqtt-type">
+        <xsl:with-param name="type" select="type"/>
+      </xsl:call-template>
     </xsl:otherwise>
   </xsl:choose>
+  <xsl:if test="count(defval) > 0"> = <xsl:value-of select="defval"/>
+  </xsl:if>
   <xsl:if test="not(position() = last())">,</xsl:if>
 </xsl:template>
 
diff --git a/include/async_mqtt5/mqtt_client.hpp b/include/async_mqtt5/mqtt_client.hpp
index 0b23960..f980769 100644
--- a/include/async_mqtt5/mqtt_client.hpp
+++ b/include/async_mqtt5/mqtt_client.hpp
@@ -19,10 +19,10 @@ namespace asio = boost::asio;
 /**
  * \brief \__MQTT\__ client used to connect and communicate with a Broker.
  *
- * \tparam StreamType Type of the underlying transport protocol used to transfer
+ * \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
  * ordered and lossless.
- * \tparam TlsContext Type of the context object used in TLS/SSL connections.
+ * \tparam \__TlsContext\__ Type of the context object used in TLS/SSL connections.
  */
 template <
 	typename StreamType,
@@ -63,9 +63,9 @@ public:
 	{}
 
 	/**
-	 * \brief Constructs a client with given parameters.
+	 * \brief Constructs a Client with given parameters.
 	 *
-	 * \tparam ExecutionContext Type of a concrete execution context.
+	 * \tparam \__ExecutionContext\__ Type of a concrete execution context.
 	 * \param context Execution context whose executor will be associated with the Client.
 	 * \param cnf 
 	 * \param tls_context A context object used in TLS/SLL connection.
@@ -85,6 +85,7 @@ public:
 		mqtt_client(context.get_executor(), cnf, std::move(tls_context))
 	{}
 
+	/// Copy constructor.
 	mqtt_client(const mqtt_client& other) = delete;
 
 	/**
@@ -139,7 +140,7 @@ public:
 	 * \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.
+	 * \attention The Client cannot be used before calling \ref mqtt_client::run again.
 	 */
 	void cancel() {
 		get_executor().execute([svc_ptr = _svc_ptr]() {
@@ -250,10 +251,10 @@ 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` \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
+	 *		- \link async_mqtt5::client::error::pid_overrun \endlink
+	 *		- \link async_mqtt5::client::error::qos_not_supported \endlink
+	 *		- \link async_mqtt5::client::error::retain_not_available \endlink
+	 *		- \link async_mqtt5::client::error::topic_alias_maximum_reached \endlink
 	 *
 	 * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
 	 */
@@ -292,7 +293,7 @@ public:
 	 *
 	 * \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 Application Messages can be received
 	 * with \ref mqtt_client::async_receive function.
 	 *
 	 * \param topics A list of \ref subscribe_topic of interest.
@@ -316,7 +317,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` \n
-	 *		- \link client::error::pid_overrun \endlink
+	 *		- \link async_mqtt5::client::error::pid_overrun \endlink
 	 *
 	 * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
 	 */
@@ -349,7 +350,7 @@ public:
 	 *
 	 * \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 Application Messages can be received
 	 * with \ref mqtt_client::async_receive function.
 	 *
 	 * \param topic A \ref subscribe_topic of interest.
@@ -373,7 +374,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` \n
-	 *		- \link client::error::pid_overrun \endlink
+	 *		- \link async_mqtt5::client::error::pid_overrun \endlink
 	 *
 	 * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
 	 */
@@ -418,7 +419,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` \n
-	 *		- \link client::error::pid_overrun \endlink
+	 *		- \link async_mqtt5::client::error::pid_overrun \endlink
 	 *
 	 * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
 	 */
@@ -474,7 +475,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` \n
-	 *		- \link client::error::pid_overrun \endlink
+	 *		- \link async_mqtt5::client::error::pid_overrun \endlink
 	 *
 	 * Refer to the section on \__ERROR_HANDLING\__ to find the underlying causes for each error code.
 	 */
@@ -538,7 +539,7 @@ public:
 	 * \details Send a \__DISCONNECT\__ packet to the Broker with a Reason Code
 	 * describing the reason for disconnection.
 	 *
-	 * \note This function will close the Client. See \ref mqtt_client::cancel.
+	 * \attention 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.
@@ -580,7 +581,7 @@ public:
 	 * \ref reason_codes::normal_disconnection describing
 	 * the reason for disconnection.
 	 *
-	 * \note This function will close the Client. See \ref mqtt_client::cancel.
+	 * \attention 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.
diff --git a/include/async_mqtt5/types.hpp b/include/async_mqtt5/types.hpp
index 6149526..79c1c82 100644
--- a/include/async_mqtt5/types.hpp
+++ b/include/async_mqtt5/types.hpp
@@ -86,13 +86,13 @@ struct subscribe_options {
 	 * \brief Representation of the Retain As Published Subscribe Option.
 	 *
 	 * \details A Subscribe Option indicating whether or not Application Messages forwarded
-	 * using this subscription keep the \ref retain_e flag they were published with.
+	 * using this subscription keep the \__RETAIN\__ flag they were published with.
 	 */
 	enum class retain_as_published_e : std::uint8_t {
-		/** Application Messages have the \ref retain_e flag set to 0. */
+		/** Application Messages have the \__RETAIN\__ flag set to 0. */
 		dont = 0b0,
 
-		/** Application Messages keep the \ref retain_e flag they were published with. */
+		/** Application Messages keep the \__RETAIN\__ flag they were published with. */
 		retain = 0b1
 	};
 
@@ -114,13 +114,13 @@ struct subscribe_options {
 	};
 
 
-	/// Maximum \ref qos_e level at which the Server can send Application Messages to the Client.
+	/// Maximum \__QOS\__ level at which the Server can send Application Messages to the Client.
 	qos_e max_qos = qos_e::exactly_once;
 
 	/// Option determining if Application Messages will be forwarded to a connection with an equal ClientID.
 	no_local_e no_local = no_local_e::yes;
 
-	/// Option determining if Application Message will keep their \ref retain_e flag.
+	/// Option determining if Application Message will keep their \__RETAIN\__ flag.
 	retain_as_published_e retain_as_published = retain_as_published_e::retain;
 
 	/// Option determining if retained messages are sent when the subscription is established.