From 710dd558db5b06d9908b564dc9f7ee3d305a5efb Mon Sep 17 00:00:00 2001
From: ruben <rubenperez038@gmail.com>
Date: Sun, 5 Apr 2020 14:56:18 +0100
Subject: [PATCH] Updated docs on SSL

---
 TODO.txt                                  |  3 +--
 examples/query_sync.cpp                   |  3 +++
 include/boost/mysql/connection_params.hpp | 18 +++++++++++++++---
 3 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/TODO.txt b/TODO.txt
index cbfc65c6..5adde7df 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -1,6 +1,5 @@
 SSL
-	Docs on SSL
-	Update example docs on SSL
+	SSL mode "enable" (not being required)
 Multiresultset
 	Text protocol
 	Binary protocol (stored procedures)
diff --git a/examples/query_sync.cpp b/examples/query_sync.cpp
index 025cedcd..c143d6ad 100644
--- a/examples/query_sync.cpp
+++ b/examples/query_sync.cpp
@@ -55,6 +55,9 @@ void main_impl(int argc, char** argv)
 		argv[2],		       // password
 		"mysql_asio_examples"  // database to use; leave empty or omit the parameter for no database
 	);
+	// connection_params accepts an optional ssl_options argument describing
+	// whether to use TLS on the connection or not. By default, TLS is enabled
+	// and required.
 
 	boost::asio::io_context ctx;
 
diff --git a/include/boost/mysql/connection_params.hpp b/include/boost/mysql/connection_params.hpp
index 7f5be751..89b12471 100644
--- a/include/boost/mysql/connection_params.hpp
+++ b/include/boost/mysql/connection_params.hpp
@@ -7,18 +7,30 @@
 namespace boost {
 namespace mysql {
 
+/// Determines whether to use TLS for the connection or not.
 enum class ssl_mode
 {
-	disable,
-	require
+	disable, ///< Never use TLS
+	require  ///< Always use TLS; abort the connection if the server does not support it.
 };
 
+/**
+ * \brief Connection options regarding TLS.
+ * \details At the moment, contains only the \ref ssl_mode, which
+ * indicates whether to use TLS on the connection or not.
+ */
 class ssl_options
 {
 	ssl_mode mode_;
 public:
+	/**
+	 * \brief Default and initialization constructor.
+	 * \details By default, SSL is required for the connection to be established.
+	 */
 	explicit ssl_options(ssl_mode mode=ssl_mode::require) noexcept:
 		mode_(mode) {}
+
+	/// Retrieves the TLS mode to be used for the connection.
 	ssl_mode mode() const noexcept { return mode_; }
 };
 
@@ -40,7 +52,7 @@ public:
 		std::string_view password,  ///< Password for that username, possibly empty.
 		std::string_view db = "",   ///< Database to use, or empty string for no database.
 		collation connection_col = collation::utf8_general_ci, ///< The default character set and collation for the connection.
-		const ssl_options& opts = ssl_options()
+		const ssl_options& opts = ssl_options() ///< The TLS options to use with this connection.
 	) :
 		username_(username),
 		password_(password),