Doc fixes

Summary: related to T15258, T15261 - improved TlsContext documentation - hide `detail::is_authenticator` explicitly from docs - remove ExecutionContext from concepts, now it just links to asio docs - fix user_property and subscription_identifier value type in property docs Reviewers: ivica Reviewed By: ivica Subscribers: iljazovic, miljen Differential Revision: https://repo.mireo.local/D33857
2025-02-20 12:45:44 +01:00
parent 7292ca453a
commit 1fe10dd6a3
22 changed files with 38 additions and 54 deletions
--- a/doc/config.json
+++ b/doc/config.json
@ -11,7 +11,6 @@
        "\\btypename ExecutionContext\\b": "typename __ExecutionContext__",
        "\\btypename TlsContext\\b": "typename __TlsContext__",
        "\\btypename StreamType\\b": "typename __StreamType__",
-        "\\bis_authenticator\\b": "__is_authenticator__",
        "\\btypename LoggerType\\b": "typename __LoggerType__"
    }
 }
--- a/doc/qbk/00_main.qbk
+++ b/doc/qbk/00_main.qbk
@ -42,10 +42,10 @@

 [def __CompletionToken__ [@boost:/doc/html/boost_asio/reference/asynchronous_operations.html#boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers ['CompletionToken]]]
 [def __Executor__ [@boost:/doc/html/boost_asio/reference/Executor1.html ['Executor]]]
-[def __ExecutionContext__ [reflink ExecutionContext ['ExecutionContext]]]
+[def __ExecutionContext__ [@boost:/doc/html/boost_asio/reference/ExecutionContext.html ['ExecutionContext]]]
 [def __StreamType__ [reflink StreamType ['StreamType]]]
 [def __TlsContext__ [reflink TlsContext ['TlsContext]]]
-[def __is_authenticator__ [reflink is_authenticator ['is_authenticator]]]
+[def __Authenticator__ [reflink Authenticator ['Authenticator]]]
 [def __LoggerType__ [reflink LoggerType ['LoggerType]]]

 [def __Boost__ [@https://www.boost.org/ Boost]]
@ -159,10 +159,9 @@
 [block'''<part label="Two: Reference">''']
 [include reference.qbk]
 [include reference/Error_handling.qbk]
-[include reference/concepts/ExecutionContext.qbk]
 [include reference/concepts/StreamType.qbk]
 [include reference/concepts/TlsContext.qbk]
-[include reference/concepts/is_authenticator.qbk]
+[include reference/concepts/Authenticator.qbk]
 [include reference/concepts/LoggerType.qbk]
 [include reference/reason_codes/Reason_codes.qbk]
 [include reference/properties/will_props.qbk]
--- a/doc/qbk/reference/concepts/is_authenticator.qbk
+++ b/doc/qbk/reference/concepts/is_authenticator.qbk
@ -4,9 +4,9 @@
    (See accompanying file LICENSE or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]

-[section:is_authenticator is_authenticator concept]
+[section:Authenticator Authenticator concept]

-A type `Authenticator` satisfies `is_authenticator` concept if it satisifes the requirements listed below.
+A type `T` satisfies `Authenticator` concept if it satisifes the requirements listed below.

 [table
    [[operation] [type] [arguments]]
@ -28,5 +28,4 @@ A type `Authenticator` satisfies `is_authenticator` concept if it satisifes the
    ]
 ]

-
 [endsect]
--- a/doc/qbk/reference/concepts/ExecutionContext.qbk
+++ b/doc/qbk/reference/concepts/ExecutionContext.qbk
@ -1,15 +0,0 @@
-[/
-    Copyright (c) 2023-2025 Ivica Siladic, Bruno Iljazovic, Korina Simicevic
-    Distributed under the Boost Software License, Version 1.0.
-    (See accompanying file LICENSE or copy at http://www.boost.org/LICENSE_1_0.txt)
-]
-
-[section:ExecutionContext ExecutionContext concept]
-
-`ExecutionContext` represents a place where function objects will be executed.
-
-`ExecutionContext` type must be convertible to [asioreflink execution_context execution_context] which
-is a base class for concrete execution context types. 
-The [asioreflink io_context io_context] type is an example of a derived type.
-
-[endsect]
--- a/doc/qbk/reference/concepts/TlsContext.qbk
+++ b/doc/qbk/reference/concepts/TlsContext.qbk
@ -6,9 +6,13 @@

 [section:TlsContext TlsContext concept]

-`TlsContext` represents an object that defines user's configuration
-for establishing TLS/SSL connections.
+`TlsContext` represents an object that defines the user's configuration for establishing TLS/SSL connections.
+If TLS/SSL is not required, this parameter defaults to `std::monostate`.

-The type [asioreflink ssl__context ssl::context] meets these requirements.
+The __Client__ treats the `TlsContext` object as an opaque entity.
+It is primarily utilized when creating the underlying transport stream and is not directly manipulated by the __Client__.
+
+For instance, establishing a secure connection using using __SSL_STREAM__ requires __SSL_CONTEXT__ as the `TlsContext` type.
+An example of this can be found in the [link mqtt5.hello_world_over_tls hello_world_over_tls.cpp] example.

 [endsect]
--- a/doc/qbk/reference/properties/auth_props.qbk
+++ b/doc/qbk/reference/properties/auth_props.qbk
@ -16,7 +16,7 @@ This section lists all possible __AUTH__ Properties and describes their usage:
    [[authentication_method] [`std::string`] [A UTF-8 Encoded String containing the name of the authentication method used for extended authentication.]]
    [[authentication_data] [`std::string`] [Binary Data containing authentication data. The contents of the data are defined by the authentication method.]]
    [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
-    [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
+    [[user_property] [`std::vector<std::pair<std::string, std::string>>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
        This property may be used to provide additional diagnostic or other information. ]]
 ]

--- a/doc/qbk/reference/properties/connack_props.qbk
+++ b/doc/qbk/reference/properties/connack_props.qbk
@ -21,7 +21,7 @@ This section lists all possible __CONNACK__ Properties and describes their usage
    [[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.]]
-    [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
+    [[user_property] [`std::vector<std::pair<std::string, std::string>>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
        The meaning of these properties is not defined by the specification.]]
    [[wildcard_subscription_available] [`uint8_t`] [A value of 0 means that Wildcard Subscriptions are not supported. 
        A value of 1 means they are supported. If not present, they are supported.]]
--- a/doc/qbk/reference/properties/connect_props.qbk
+++ b/doc/qbk/reference/properties/connect_props.qbk
@ -21,7 +21,7 @@ This section lists all possible __CONNECT__ Properties and describes their usage
    [[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::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
+    [[user_property] [`std::vector<std::pair<std::string, std::string>>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
        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.]]
    [[authentication_data] [`std::string`] [Binary Data containing authentication data. The contents of the data are defined by the authentication method.]]
--- a/doc/qbk/reference/properties/disconnect_props.qbk
+++ b/doc/qbk/reference/properties/disconnect_props.qbk
@ -15,7 +15,7 @@ This section lists all possible __DISCONNECT__ Properties and describes their us
    [[Identifier] [Value type] [Description]]
    [[session_expiry_interval] [`uint32_t`] [Represents the Session Expiry Internal in seconds. Can only be sent by the Client.]]
    [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
-    [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
+    [[user_property] [`std::vector<std::pair<std::string, std::string>>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
        This property may be used to provide additional diagnostic or other information. ]]
    [[server_reference] [`std::string`] [A UTF-8 Encoded String which can be used by the Client to identfy another Server to use.]]
 ]
--- a/doc/qbk/reference/properties/puback_props.qbk
+++ b/doc/qbk/reference/properties/puback_props.qbk
@ -14,7 +14,7 @@ This section lists all possible __PUBACK__ Properties and describes their usage:
 [table:puback_props PUBACK properties
    [[Identifier] [Value type] [Description]]
    [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
-    [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
+    [[user_property] [`std::vector<std::pair<std::string, std::string>>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
        This property may be used to provide additional diagnostic or other information. ]]
 ]

--- a/doc/qbk/reference/properties/pubcomp_props.qbk
+++ b/doc/qbk/reference/properties/pubcomp_props.qbk
@ -14,7 +14,7 @@ This section lists all possible __PUBCOMP__ Properties and describes their usage
 [table:pubcomp_props PUBCOMP properties
    [[Identifier] [Value type] [Description]]
    [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
-    [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
+    [[user_property] [`std::vector<std::pair<std::string, std::string>>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
        This property may be used to provide additional diagnostic or other information. ]]
 ]

--- a/doc/qbk/reference/properties/publish_props.qbk
+++ b/doc/qbk/reference/properties/publish_props.qbk
@ -18,9 +18,9 @@ This section lists all possible __PUBLISH__ Properties and describes their usage
    [[topic_alias] [`uint16_t`] [Two Byte integer representing the Topic Alias, an integer value that is used to identify the Topic instead of using the Topic Name.]]
    [[response_topic] [`std::string`] [A UTF-8 Encoded String which is used as the Topic Name for a response message.]]
    [[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.]]
-    [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
+    [[user_property] [`std::vector<std::pair<std::string, std::string>>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
        The meaning of these properties is not defined by the specification.]]
-    [[subscription_identifier] [`int32_t`] [Identifier of the matching subscription. If there are multiple matching subscriptions, multiple identifiers may be included.]]
+    [[subscription_identifier] [`boost::mqtt5::prop::subscription_identifiers`] [Identifier of the matching subscription. If there are multiple matching subscriptions, multiple identifiers may be included.]]
    [[content_type] [`std::string`] [A UTF-8 Encoded String describing the content of the Application Message.]]
 ]

--- a/doc/qbk/reference/properties/pubrec_props.qbk
+++ b/doc/qbk/reference/properties/pubrec_props.qbk
@ -14,7 +14,7 @@ This section lists all possible __PUBREC__ Properties and describes their usage:
 [table:pubrec_props PUBREC properties
    [[Identifier] [Value type] [Description]]
    [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
-    [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
+    [[user_property] [`std::vector<std::pair<std::string, std::string>>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
        This property may be used to provide additional diagnostic or other information. ]]
 ]

--- a/doc/qbk/reference/properties/pubrel_props.qbk
+++ b/doc/qbk/reference/properties/pubrel_props.qbk
@ -14,7 +14,7 @@ This section lists all possible __PUBREL__ Properties and describes their usage:
 [table:pubrel_props PUBREL properties
    [[Identifier] [Value type] [Description]]
    [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
-    [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
+    [[user_property] [`std::vector<std::pair<std::string, std::string>>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
        This property may be used to provide additional diagnostic or other information. ]]
 ]

--- a/doc/qbk/reference/properties/suback_props.qbk
+++ b/doc/qbk/reference/properties/suback_props.qbk
@ -14,7 +14,7 @@ This section lists all possible __SUBACK__ Properties and describes their usage:
 [table:suback_props SUBACK properties
    [[Identifier] [Value type] [Description]]
    [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
-    [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
+    [[user_property] [`std::vector<std::pair<std::string, std::string>>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
        This property may be used to provide additional diagnostic or other information. ]]
 ]

--- a/doc/qbk/reference/properties/subscribe_props.qbk
+++ b/doc/qbk/reference/properties/subscribe_props.qbk
@ -13,8 +13,8 @@ This section lists all possible __SUBSCRIBE__ Properties and describes their usa

 [table:subscribe_props SUBSCRIBE properties
    [[Identifier] [Value type] [Description]]
-    [[subscription_identifier] [`int32_t`] [Identifier of the Subscription in range of 1 to 268,435,455.]]
-    [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
+    [[subscription_identifier] [`boost::mqtt5::prop::subscription_identifiers`] [Identifier of the Subscription in range of 1 to 268,435,455.]]
+    [[user_property] [`std::vector<std::pair<std::string, std::string>>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
        This property can be used to send subscription related properties from the Client to the Server. 
        The meaning of these properties is not defined by the specification ]]
 ]
--- a/doc/qbk/reference/properties/unsuback_props.qbk
+++ b/doc/qbk/reference/properties/unsuback_props.qbk
@ -14,7 +14,7 @@ This section lists all possible __UNSUBACK__ Properties and describes their usag
 [table:unsuback_props UNSUBACK properties
    [[Identifier] [Value type] [Description]]
    [[reason_string] [`std::string`] [A UTF-8 Encoded String representing the reason associated with this response.]]
-    [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
+    [[user_property] [`std::vector<std::pair<std::string, std::string>>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
        This property may be used to provide additional diagnostic or other information. ]]
 ]

--- a/doc/qbk/reference/properties/unsubscribe_props.qbk
+++ b/doc/qbk/reference/properties/unsubscribe_props.qbk
@ -13,7 +13,7 @@ This section lists all possible __UNSUBSCRIBE__ Properties and describes their u

 [table:unsubscribe_props UNSUBSCRIBE properties
    [[Identifier] [Value type] [Description]]
-    [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
+    [[user_property] [`std::vector<std::pair<std::string, std::string>>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
        This property can be used to send subscription related properties from the Client to the Server. 
        The meaning of these properties is not defined by the specification ]]
 ]
--- a/doc/qbk/reference/properties/will_props.qbk
+++ b/doc/qbk/reference/properties/will_props.qbk
@ -20,7 +20,7 @@ This section lists all possible [reflink2 will Will] Properties and describes th
    [[content_type] [`std::string`] [A UTF-8 Encoded String describing the content of the Will Message.]]
    [[response_topic] [`std::string`] [A UTF-8 Encoded String which is used as the Topic Name for a response message.]]
    [[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.]]
-    [[user_property] [`std::pair<std::string, std::string>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
+    [[user_property] [`std::vector<std::pair<std::string, std::string>>`] [Name, value pair (__UTF8_STRING_PAIR__) defining User Property. There can be multiple pairs in one packet. 
        The meaning of these properties is not defined by the specification.]]
 ]

--- a/doc/qbk/reference/quickref.xml
+++ b/doc/qbk/reference/quickref.xml
@ -23,10 +23,9 @@
        </simplelist>
        <bridgehead renderas="sect3">Concepts</bridgehead>
        <simplelist type="vert" columns="1">
-          <member><link linkend="mqtt5.ref.ExecutionContext">ExecutionContext</link></member>
          <member><link linkend="mqtt5.ref.StreamType">StreamType</link></member>
          <member><link linkend="mqtt5.ref.TlsContext">TlsContext</link></member>
-          <member><link linkend="mqtt5.ref.is_authenticator">is_authenticator</link></member>
+          <member><link linkend="mqtt5.ref.Authenticator">Authenticator</link></member>
        </simplelist>
      </entry>
      <entry valign="top">
--- a/include/boost/mqtt5/mqtt_client.hpp
+++ b/include/boost/mqtt5/mqtt_client.hpp
@ -131,15 +131,13 @@ public:

    /**
     * \brief Move-construct an mqtt_client from another.
-     *
-     * \details Moved-from client can only be destructed
     */
    mqtt_client(mqtt_client&&) noexcept = default;

    /**
     * \brief Move assignment operator.
     *
-     * \details Cancels this client first. Moved-from client can only be destructed.
+     * \details Cancels this client first.
     */
    mqtt_client& operator=(mqtt_client&& other) noexcept {
        _impl->cancel();
@ -313,7 +311,7 @@ public:
     * Re-authentication can be initiated by calling \ref re_authenticate.
     *
     * \param authenticator Object that will be stored (move-constructed or by reference)
-     * and used for authentication. It needs to satisfy \__is_authenticator\__ concept.
+     * and used for authentication. It needs to satisfy \__Authenticator\__ concept.
     *
     * \attention This function takes action when the client is in a non-operational state,
     * meaning the \ref async_run function has not been invoked.
@ -321,11 +319,12 @@ public:
     * before the \ref async_run function is invoked again.
     *
     */
-    template <
-        typename Authenticator,
-        std::enable_if_t<detail::is_authenticator<Authenticator>, bool> = true
-    >
+    template <typename Authenticator>
    mqtt_client& authenticator(Authenticator&& authenticator) {
+        static_assert(
+            detail::is_authenticator<Authenticator>,
+            "The type does not satisfy the Authenticator concept"
+        );
        _impl->authenticator(std::forward<Authenticator>(authenticator));
        return *this;
    }
--- a/include/boost/mqtt5/types.hpp
+++ b/include/boost/mqtt5/types.hpp
@ -81,12 +81,12 @@ enum class auth_step_e {
    /** \brief The Client needs to send initial authentication data. */
    client_initial,

-    /** \brief Server responded with reason_codes.continue_authentication and possibly
+    /** \brief Server responded with \ref reason_codes::continue_authentication and possibly
     * authentication data, the Client needs to send further authentication data.
     */
    server_challenge,

-    /** \brief Server responded with reason_codes.success and final
+    /** \brief Server responded with \ref reason_codes::success and final
     * authentication data, which the Client validates.
     */
    server_final