feedc0de/boost_mqtt5
1
0
Fork 0
forked from boostorg/mqtt5
Code Pull Requests Activity

[mqtt-client] some doc fixes

Browse Source 
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
This commit is contained in:
Korina Šimičević
2023-10-26 12:31:02 +02:00
parent bc882cb6ac
commit 2f1f910552
7 changed files with 206 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
doc/Jamfile
View File

@@ -29,6 +29,11 @@ import boostbook ;
make xml/index.xml make xml/index.xml
: :
reference.dox reference.dox
# additional dependencies
../include/async_mqtt5/error.hpp
../include/async_mqtt5/types.hpp
../include/async_mqtt5/mqtt_client.hpp
: :
@call-doxygen @call-doxygen
; ;

10
doc/qbk/00_main.qbk
View File

@@ -15,7 +15,7 @@
[template nochunk[] [block '''<?dbhtml stop-chunking?>''']] [template nochunk[] [block '''<?dbhtml stop-chunking?>''']]
[template mdash[] '''&mdash; '''] [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 include_file[path][^<'''<ulink url="GITHUB_LINK">'''[path]'''</ulink>'''>]]
[template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>'''] [template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>''']
[template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></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 __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 __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 __ExecutionContext__ [reflink2 ExecutionContext ExecutionContext]]
[def __StreamType__ [reflink2 StreamType ['StreamType]]] [def __StreamType__ [reflink2 StreamType StreamType]]
[def __TlsContext__ [reflink2 TlsContext ['TlsContext]]] [def __TlsContext__ [reflink2 TlsContext TlsContext]]
[def __Boost__ [@https://www.boost.org/ Boost]] [def __Boost__ [@https://www.boost.org/ Boost]]
[def __Asio__ [@boost:/libs/asio/index.html Boost.Asio]] [def __Asio__ [@boost:/libs/asio/index.html Boost.Asio]]

2
doc/qbk/reference/Error_handling.qbk
View File

@@ -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. This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish] calls.
]] ]]
[[`async_mqtt5::client::error::retain_not_available`] [ [[`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__). 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. This error code is exclusive to completion handlers associated with [refmem mqtt_client async_publish] calls.
]] ]]

2
doc/reference.dox
View File

@@ -32,7 +32,7 @@ SUBGROUPING = YES
# Build related configuration options # Build related configuration options
#--------------------------------------------------------------------------- #---------------------------------------------------------------------------
EXTRACT_ALL = YES EXTRACT_ALL = YES
EXTRACT_PRIVATE = YES EXTRACT_PRIVATE = NO
EXTRACT_STATIC = YES EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = NO EXTRACT_LOCAL_CLASSES = NO
EXTRACT_LOCAL_METHODS = NO EXTRACT_LOCAL_METHODS = NO

204
doc/reference.xsl
View File

@@ -420,14 +420,18 @@
<xsl:apply-templates mode="markup"/> <xsl:apply-templates mode="markup"/>
</xsl:when> </xsl:when>
<xsl:when test="@kind='see'"> <xsl:when test="@kind='see'">
[heading See More]
<xsl:apply-templates mode="markup"/>
</xsl:when> </xsl:when>
<xsl:when test="@kind='note'"> <xsl:when test="@kind='note'">
[heading Remarks] [note
<xsl:apply-templates mode="markup"/> <xsl:apply-templates mode="markup"/>
]
</xsl:when> </xsl:when>
<xsl:when test="@kind='attention'"> <xsl:when test="@kind='attention'">
[heading Attention] [important
<xsl:apply-templates mode="markup"/> <xsl:apply-templates mode="markup"/>
]
</xsl:when> </xsl:when>
<xsl:when test="@kind='par'"> <xsl:when test="@kind='par'">
<xsl:if test="not(starts-with(title, 'Concepts:'))"> <xsl:if test="not(starts-with(title, 'Concepts:'))">
@@ -634,6 +638,13 @@
<xsl:value-of name="text" select="$ref-name"/> <xsl:value-of name="text" select="$ref-name"/>
<xsl:text>`]</xsl:text> <xsl:text>`]</xsl:text>
</xsl:when> </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:otherwise>
<xsl:text>`</xsl:text> <xsl:text>`</xsl:text>
<xsl:value-of select="."/> <xsl:value-of select="."/>
@@ -847,14 +858,14 @@
<xsl:if test="starts-with($name, '~')"> [destructor]</xsl:if> <xsl:if test="starts-with($name, '~')"> [destructor]</xsl:if>
<xsl:if test="@static='yes'"> [static]</xsl:if> <xsl:if test="@static='yes'"> [static]</xsl:if>
<xsl:text>] <xsl:text>]
[</xsl:text><xsl:value-of select="briefdescription"/> [</xsl:text><xsl:apply-templates select="briefdescription" mode="markup"/>
</xsl:if> </xsl:if>
<xsl:if test="not($overload-position = 1) and not(briefdescription = preceding-sibling::*/briefdescription)"> <xsl:if test="not($overload-position = 1) and not(briefdescription = preceding-sibling::*/briefdescription)">
<xsl:value-of select="$newline"/> <xsl:value-of select="$newline"/>
<xsl:text> [hr]</xsl:text> <xsl:text> [hr]</xsl:text>
<xsl:value-of select="$newline"/> <xsl:value-of select="$newline"/>
<xsl:text> </xsl:text> <xsl:text> </xsl:text>
<xsl:value-of select="briefdescription"/> <xsl:apply-templates select="briefdescription" mode="markup"/>
</xsl:if> </xsl:if>
<xsl:if test="$overload-position = $overload-count"> <xsl:if test="$overload-position = $overload-count">
<xsl:text>] <xsl:text>]
@@ -901,14 +912,14 @@
<xsl:if test="starts-with($name, '~')"> [destructor]</xsl:if> <xsl:if test="starts-with($name, '~')"> [destructor]</xsl:if>
<xsl:if test="@static='yes'"> [static]</xsl:if> <xsl:if test="@static='yes'"> [static]</xsl:if>
<xsl:text>] <xsl:text>]
[</xsl:text><xsl:value-of select="briefdescription"/> [</xsl:text><xsl:apply-templates select="briefdescription" mode="markup"/>
</xsl:if> </xsl:if>
<xsl:if test="not($overload-position = 1) and not(briefdescription = preceding-sibling::*/briefdescription)"> <xsl:if test="not($overload-position = 1) and not(briefdescription = preceding-sibling::*/briefdescription)">
<xsl:value-of select="$newline"/> <xsl:value-of select="$newline"/>
<xsl:text> [hr]</xsl:text> <xsl:text> [hr]</xsl:text>
<xsl:value-of select="$newline"/> <xsl:value-of select="$newline"/>
<xsl:text> </xsl:text> <xsl:text> </xsl:text>
<xsl:value-of select="briefdescription"/> <xsl:apply-templates select="briefdescription" mode="markup"/>
</xsl:if> </xsl:if>
<xsl:if test="$overload-position = $overload-count"> <xsl:if test="$overload-position = $overload-count">
<xsl:text>] <xsl:text>]
@@ -956,14 +967,14 @@
<xsl:if test="starts-with($name, '~')"> [destructor]</xsl:if> <xsl:if test="starts-with($name, '~')"> [destructor]</xsl:if>
<xsl:if test="@static='yes'"> [static]</xsl:if> <xsl:if test="@static='yes'"> [static]</xsl:if>
<xsl:text>] <xsl:text>]
[</xsl:text><xsl:value-of select="briefdescription"/> [</xsl:text><xsl:apply-templates select="briefdescription" mode="markup"/>
</xsl:if> </xsl:if>
<xsl:if test="not($overload-position = 1) and not(briefdescription = preceding-sibling::*/briefdescription)"> <xsl:if test="not($overload-position = 1) and not(briefdescription = preceding-sibling::*/briefdescription)">
<xsl:value-of select="$newline"/> <xsl:value-of select="$newline"/>
<xsl:text> [hr]</xsl:text> <xsl:text> [hr]</xsl:text>
<xsl:value-of select="$newline"/> <xsl:value-of select="$newline"/>
<xsl:text> </xsl:text> <xsl:text> </xsl:text>
<xsl:value-of select="briefdescription"/> <xsl:apply-templates select="briefdescription" mode="markup"/>
</xsl:if> </xsl:if>
<xsl:if test="$overload-position = $overload-count"> <xsl:if test="$overload-position = $overload-count">
<xsl:text>] <xsl:text>]
@@ -985,7 +996,7 @@
[[link async_mqtt5.ref.<xsl:value-of select="$class-id"/>.<xsl:value-of select="name"/> [[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:text> </xsl:text>[*<xsl:value-of select="name"/><xsl:text>]]</xsl:text>
<xsl:if test="@static='yes'"> [static]</xsl:if>] <xsl:if test="@static='yes'"> [static]</xsl:if>]
[<xsl:value-of select="briefdescription"/>] [<xsl:apply-templates select="briefdescription" mode="markup"/>]
] ]
</xsl:for-each> </xsl:for-each>
] ]
@@ -1197,12 +1208,18 @@
<xsl:with-param name="name" select="type"/> <xsl:with-param name="name" select="type"/>
</xsl:call-template> </xsl:call-template>
</xsl:variable> </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:if test="string-length($stripped-type) &gt; 0">
<xsl:value-of select="$stripped-type"/><xsl:text> </xsl:text> <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 </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="$id"/>.overload<xsl:value-of select="position()"/><xsl:text> </xsl:text><xsl:value-of
select="name"/>]``(<xsl:apply-templates select="param" 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> `` [''''&amp;raquo;'''</xsl:text>
<xsl:text> [link async_mqtt5.ref.</xsl:text> <xsl:text> [link async_mqtt5.ref.</xsl:text>
<xsl:value-of select="$class-id"/>.<xsl:value-of <xsl:value-of select="$class-id"/>.<xsl:value-of
@@ -1261,7 +1278,9 @@
</xsl:when> </xsl:when>
</xsl:choose> </xsl:choose>
<xsl:if test="count(detaileddescription/*) &gt; 0">
[heading Description] [heading Description]
</xsl:if>
<xsl:text> <xsl:text>
</xsl:text><xsl:apply-templates select="detaileddescription" mode="markup"/> </xsl:text><xsl:apply-templates select="detaileddescription" mode="markup"/>
@@ -1361,12 +1380,23 @@
[table [table
[[Name] [Description]] [[Name] [Description]]
<xsl:for-each select="enumvalue"> <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:for-each>
] ]
</xsl:if> </xsl:if>
</xsl:template> </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:template name="function">
<xsl:text> <xsl:text>
@@ -1387,42 +1417,148 @@
<xsl:with-param name="name" select="type"/> <xsl:with-param name="name" select="type"/>
</xsl:call-template> </xsl:call-template>
</xsl:variable> </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 <xsl:text> </xsl:text><xsl:if test="@static='yes'">static </xsl:if><xsl:if
test="@virt='virtual'">virtual </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> 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" <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>
<xsl:template match="templateparamlist" mode="class-detail"> <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>
<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:template match="param" mode="class-detail-template">
<xsl:text> <xsl:text>
</xsl:text> </xsl:text>
<xsl:choose> <xsl:choose>
<xsl:when test="type = 'typename CompletionToken'"> <xsl:when test="contains(type, 'typename')">
<xsl:text>typename __CompletionToken__</xsl:text> <xsl:call-template name="mqtt-template">
</xsl:when> <xsl:with-param name="qualified-name" select="type"/>
<xsl:when test="type = 'typename ExecutionContext'"> </xsl:call-template>
<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> </xsl:when>
<xsl:otherwise> <xsl:otherwise>
<xsl:value-of select="type"/> <xsl:call-template name="mqtt-type">
<xsl:text> </xsl:text> <xsl:with-param name="type" select="type"/>
<xsl:value-of select="declname"/> </xsl:call-template>
</xsl:otherwise> </xsl:otherwise>
</xsl:choose> </xsl:choose>
<xsl:if test="count(defval) > 0"> = <xsl:value-of select="defval"/> <xsl:if test="count(defval) > 0"> = <xsl:value-of select="defval"/>
@@ -1443,11 +1579,13 @@
<xsl:value-of select="array"/> <xsl:value-of select="array"/>
</xsl:when> </xsl:when>
<xsl:otherwise> <xsl:otherwise>
<xsl:value-of select="type"/> <xsl:call-template name="mqtt-type">
<xsl:text> </xsl:text> <xsl:with-param name="type" select="type"/>
<xsl:value-of select="declname"/> </xsl:call-template>
</xsl:otherwise> </xsl:otherwise>
</xsl:choose> </xsl:choose>
<xsl:if test="count(defval) > 0"> = <xsl:value-of select="defval"/>
</xsl:if>
<xsl:if test="not(position() = last())">,</xsl:if> <xsl:if test="not(position() = last())">,</xsl:if>
</xsl:template> </xsl:template>

35
include/async_mqtt5/mqtt_client.hpp
View File

@@ -19,10 +19,10 @@ 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 * \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 * the stream of bytes between the Client and the Broker. The transport must be
* ordered and lossless. * 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 < template <
typename StreamType, 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 context Execution context whose executor will be associated with the Client.
* \param cnf * \param cnf
* \param tls_context A context object used in TLS/SLL connection. * \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)) mqtt_client(context.get_executor(), cnf, std::move(tls_context))
{} {}
/// Copy constructor.
mqtt_client(const mqtt_client& other) = delete; mqtt_client(const mqtt_client& other) = delete;
/** /**
@@ -139,7 +140,7 @@ public:
* \details All outstanding operations will complete * \details All outstanding operations will complete
* with `boost::asio::error::operation_aborted`. * 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() { void cancel() {
get_executor().execute([svc_ptr = _svc_ptr]() { 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 * The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success`\n * - `boost::system::errc::errc_t::success`\n
* - `boost::asio::error::operation_aborted` \n * - `boost::asio::error::operation_aborted` \n
* - \link client::error::pid_overrun \endlink * - \link async_mqtt5::client::error::pid_overrun \endlink
* - \link client::error::qos_not_supported \endlink * - \link async_mqtt5::client::error::qos_not_supported \endlink
* - \link client::error::retain_not_available \endlink * - \link async_mqtt5::client::error::retain_not_available \endlink
* - \link client::error::topic_alias_maximum_reached \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. * 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 * \details After the subscription has been established, the Broker will send
* PUBLISH packets to the Client to forward Application Messages that were published * 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. * with \ref mqtt_client::async_receive function.
* *
* \param topics A list of \ref subscribe_topic of interest. * \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 * The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success`\n * - `boost::system::errc::errc_t::success`\n
* - `boost::asio::error::operation_aborted` \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. * 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 * \details After the subscription has been established, the Broker will send
* \__PUBLISH\__ packets to the Client to forward Application Messages that were published * \__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. * with \ref mqtt_client::async_receive function.
* *
* \param topic A \ref subscribe_topic of interest. * \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 * The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success`\n * - `boost::system::errc::errc_t::success`\n
* - `boost::asio::error::operation_aborted` \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. * 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 * The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success`\n * - `boost::system::errc::errc_t::success`\n
* - `boost::asio::error::operation_aborted` \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. * 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 * The list of all possible error codes that this operation can finish with:\n
* - `boost::system::errc::errc_t::success`\n * - `boost::system::errc::errc_t::success`\n
* - `boost::asio::error::operation_aborted` \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. * 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 * \details Send a \__DISCONNECT\__ packet to the Broker with a Reason Code
* describing the reason for 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 reason_code Reason Code to notify * \param reason_code Reason Code to notify
* the Broker of the reason for disconnection. * the Broker of the reason for disconnection.
@@ -580,7 +581,7 @@ public:
* \ref reason_codes::normal_disconnection describing * \ref reason_codes::normal_disconnection describing
* the reason for disconnection. * 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 * \param token Completion token that will be used to produce a
* completion handler, which will be called when the operation completed. * completion handler, which will be called when the operation completed.

10
include/async_mqtt5/types.hpp
View File

@@ -86,13 +86,13 @@ struct subscribe_options {
* \brief Representation of the Retain As Published Subscribe Option. * \brief Representation of the Retain As Published Subscribe Option.
* *
* \details A Subscribe Option indicating whether or not Application Messages forwarded * \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 { 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, 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 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; qos_e max_qos = qos_e::exactly_once;
/// Option determining if Application Messages will be forwarded to a connection with an equal ClientID. /// Option determining if Application Messages will be forwarded to a connection with an equal ClientID.
no_local_e no_local = no_local_e::yes; 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; retain_as_published_e retain_as_published = retain_as_published_e::retain;
/// Option determining if retained messages are sent when the subscription is established. /// Option determining if retained messages are sent when the subscription is established.