From da2e13848acfc879fe07be92818700d56d13f393 Mon Sep 17 00:00:00 2001 From: ruben Date: Tue, 7 Apr 2020 15:20:46 +0100 Subject: [PATCH] Reviewed doxygen docs (connection & params) --- TODO.txt | 6 ++ include/boost/mysql/collation.hpp | 1 + include/boost/mysql/connection.hpp | 32 +++++++--- include/boost/mysql/connection_params.hpp | 21 +++++-- .../detail/auxiliar/async_result_macro.hpp | 13 ++++ include/boost/mysql/error.hpp | 61 ++++++++++++++----- 6 files changed, 105 insertions(+), 29 deletions(-) create mode 100644 include/boost/mysql/detail/auxiliar/async_result_macro.hpp diff --git a/TODO.txt b/TODO.txt index 6c0ce503..ff7f1e39 100644 --- a/TODO.txt +++ b/TODO.txt @@ -1,3 +1,9 @@ +Docs + Home page + Examples + Make undocumented enum values show + Autogen + Read the docs Multiresultset Text protocol Binary protocol (stored procedures) diff --git a/include/boost/mysql/collation.hpp b/include/boost/mysql/collation.hpp index fc2774b0..45ffe282 100644 --- a/include/boost/mysql/collation.hpp +++ b/include/boost/mysql/collation.hpp @@ -7,6 +7,7 @@ namespace boost { namespace mysql { /** + * \ingroup connparams * \brief A character set and a collation. * \details Names and ids for this enum correspond to the "Collation" and "Id" * fields returned by MySQL "SHOW COLLATION" statement. diff --git a/include/boost/mysql/connection.hpp b/include/boost/mysql/connection.hpp index 92b997f5..1a55bd86 100644 --- a/include/boost/mysql/connection.hpp +++ b/include/boost/mysql/connection.hpp @@ -2,18 +2,26 @@ #define MYSQL_ASIO_CONNECTION_HPP #include "boost/mysql/detail/protocol/channel.hpp" -#include "boost/mysql/detail/network_algorithms/handshake.hpp" #include "boost/mysql/detail/protocol/protocol_types.hpp" +#include "boost/mysql/detail/network_algorithms/handshake.hpp" +#include "boost/mysql/detail/auxiliar/async_result_macro.hpp" #include "boost/mysql/error.hpp" #include "boost/mysql/resultset.hpp" #include "boost/mysql/prepared_statement.hpp" #include "boost/mysql/connection_params.hpp" #include +/** + * \defgroup connection Connection + * \brief Classes and functions related to establishing + * connections with the MySQL server. + */ + namespace boost { namespace mysql { /** + * \ingroup connection * \brief A connection to a MySQL server. * \details * This is the basic object to instantiate to use the MySQL-Asio library. @@ -89,17 +97,17 @@ public: * until the operation completes, as no copy is made by the library. */ template - BOOST_ASIO_INITFN_RESULT_TYPE(CompletionToken, handshake_signature) + BOOST_MYSQL_INITFN_RESULT_TYPE(CompletionToken, handshake_signature) async_handshake(const connection_params& params, CompletionToken&& token, error_info* info = nullptr); /** * \brief Executes a SQL text query (sync with error code version). - * \detail Does not perform the actual retrieval of the data; use the various + * \details Does not perform the actual retrieval of the data; use the various * fetch functions within resultset to achieve that. + * \see resultset * * Note that query_string may contain any valid SQL, not just SELECT statements. - * If your query does not return any data, then the resultset will be empty - * (\see resultset for more details). + * If your query does not return any data, then the resultset will be empty. * * \warning After query() has returned, you should read the entire resultset * before calling any function that involves communication with the server over this @@ -116,7 +124,7 @@ public: /// Executes a SQL text query (async version). template - BOOST_ASIO_INITFN_RESULT_TYPE(CompletionToken, query_signature) + BOOST_MYSQL_INITFN_RESULT_TYPE(CompletionToken, query_signature) async_query(std::string_view query_string, CompletionToken&& token, error_info* info=nullptr); /** @@ -140,16 +148,22 @@ public: /// Prepares a statement (async version). template - BOOST_ASIO_INITFN_RESULT_TYPE(CompletionToken, prepare_statement_signature) + BOOST_MYSQL_INITFN_RESULT_TYPE(CompletionToken, prepare_statement_signature) async_prepare_statement(std::string_view statement, CompletionToken&& token, error_info* info=nullptr); }; -/// A connection to MySQL over TCP. +/** + * \ingroup connection + * \brief A connection to MySQL over a TCP socket. + */ using tcp_connection = connection; // TODO: UNIX socket connection -/// The default TCP port for the MySQL protocol. +/** + * \ingroup connection + * \brief The default TCP port for the MySQL protocol. + */ constexpr unsigned short default_port = 3306; } // mysql diff --git a/include/boost/mysql/connection_params.hpp b/include/boost/mysql/connection_params.hpp index 9fa8c215..15323d92 100644 --- a/include/boost/mysql/connection_params.hpp +++ b/include/boost/mysql/connection_params.hpp @@ -4,10 +4,19 @@ #include #include "boost/mysql/collation.hpp" +/** + * \defgroup connparams Connection parameters + * \ingroup connection + * \brief Parameters for estabilishing the connection to the MySQL server. + */ + namespace boost { namespace mysql { -/// Determines whether to use TLS for the connection or not. +/** + * \ingroup connparams + * \brief Determines whether to use TLS for the connection or not. + */ enum class ssl_mode { disable, ///< Never use TLS @@ -16,8 +25,9 @@ enum class ssl_mode }; /** + * \ingroup connparams * \brief Connection options regarding TLS. - * \details At the moment, contains only the \ref ssl_mode, which + * \details At the moment, contains only the ssl_mode, which * indicates whether to use TLS on the connection or not. */ class ssl_options @@ -27,7 +37,7 @@ public: /** * \brief Default and initialization constructor. * \details By default, SSL is enabled for the connection - * if the server supports is (\ref ssl_mode::enable). + * if the server supports is (ssl_mode::enable). */ explicit ssl_options(ssl_mode mode=ssl_mode::enable) noexcept: mode_(mode) {} @@ -38,6 +48,7 @@ public: /** + * \ingroup connparams * \brief Parameters defining how to authenticate to a MySQL server. */ class connection_params @@ -95,8 +106,8 @@ public: void set_ssl(const ssl_options& value) noexcept { ssl_ = value; } }; -} -} +} // mysql +} // boost diff --git a/include/boost/mysql/detail/auxiliar/async_result_macro.hpp b/include/boost/mysql/detail/auxiliar/async_result_macro.hpp new file mode 100644 index 00000000..d64fd017 --- /dev/null +++ b/include/boost/mysql/detail/auxiliar/async_result_macro.hpp @@ -0,0 +1,13 @@ +#ifndef INCLUDE_BOOST_MYSQL_DETAIL_AUXILIAR_ASYNC_RESULT_MACRO_HPP_ +#define INCLUDE_BOOST_MYSQL_DETAIL_AUXILIAR_ASYNC_RESULT_MACRO_HPP_ + +#include + +#ifdef BOOST_MYSQL_DOXYGEN +#define BOOST_MYSQL_INITFN_RESULT_TYPE(ct, sig) DEDUCED +#else +#define BOOST_MYSQL_INITFN_RESULT_TYPE(ct, sig) \ + BOOST_ASIO_INITFN_RESULT_TYPE(ct, sig) +#endif + +#endif /* INCLUDE_BOOST_MYSQL_DETAIL_AUXILIAR_ASYNC_RESULT_MACRO_HPP_ */ diff --git a/include/boost/mysql/error.hpp b/include/boost/mysql/error.hpp index e8f1ecd5..09cb83e6 100644 --- a/include/boost/mysql/error.hpp +++ b/include/boost/mysql/error.hpp @@ -4,33 +4,54 @@ #include #include +/** + * \defgroup error Error handling + * \brief Classes and functions used in error handling. + */ + namespace boost { namespace mysql { -/// MySQL-specific error codes. +/** + * \ingroup error + * \brief MySQL-specific error codes. + * \details Some error codes are defined by the client library, and others + * are returned from the server. For the latter, the numeric value and + * string descriptions match the ones described in the MySQL documentation. + * Only the first ones are documented here. For the latter, see + * https://dev.mysql.com/doc/refman/8.0/en/server-error-reference.html + */ enum class errc : int { - // OK - ok = 0, + ok = 0, ///< No error. // Server returned errors #include "boost/mysql/impl/server_error_enum.hpp" // Protocol errors - incomplete_message = 0x10000, - extra_bytes, - sequence_number_mismatch, - server_unsupported, - protocol_value_error, - unknown_auth_plugin, - auth_plugin_requires_ssl, - wrong_num_params + incomplete_message = 0x10000, ///< An incomplete message was received from the server. + extra_bytes, ///< Unexpected extra bytes at the end of a message were received. + sequence_number_mismatch, ///< A sequence number mismatched happened. + server_unsupported, ///< The server does not support the minimum required capabilities to establish the connection. + protocol_value_error, ///< An unexpected value was found in a server-received message. + unknown_auth_plugin, ///< The user employs an authentication plugin not known to this library. + auth_plugin_requires_ssl, ///< The authentication plugin requires the connection to use SSL. + wrong_num_params ///< The number of parameters passed to the prepared statement does not match the number of actual parameters. }; -/// An alias for boost::system error codes. +/** + * \ingroup error + * \brief An alias for boost::system error codes. + */ using error_code = boost::system::error_code; -/// Additional information about error conditions +/** + * \ingroup error + * \brief Additional information about error conditions + * \details Contains an error message describing what happened. Not all error + * conditions are able to generate this extended information - those that + * can't have an empty error message. + */ class error_info { std::string msg_; @@ -51,12 +72,22 @@ public: void clear() noexcept { msg_.clear(); } }; -/// Compare two error infos. +/** + * \relates error_info + * \brief Compare two error_info objects. + */ inline bool operator==(const error_info& lhs, const error_info& rhs) noexcept { return lhs.message() == rhs.message(); } -/// Compare two error infos. +/** + * \relates error_info + * \brief Compare two error_info objects. + */ inline bool operator!=(const error_info& lhs, const error_info& rhs) noexcept { return !(lhs==rhs); } +/** + * \relates error_info + * \brief Streams an error_info. + */ inline std::ostream& operator<<(std::ostream& os, const error_info& v) { return os << v.message(); } } // mysql