From: Razvan Becheriu <razvan@isc.org>
Date: Tue, 29 Oct 2019 10:46:27 +0000 (+0200)
Subject: [#887,!572] updated doxygen
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=297e61208024a17597b89a97fdb37062c1de3d45;p=thirdparty%2Fkea.git

[#887,!572] updated doxygen
---

diff --git a/src/lib/mysql/mysql_connection.cc b/src/lib/mysql/mysql_connection.cc
index 17a80004e4..1a54c552f2 100644
--- a/src/lib/mysql/mysql_connection.cc
+++ b/src/lib/mysql/mysql_connection.cc
@@ -27,12 +27,17 @@ bool MySqlHolder::atexit_ = []{atexit([]{mysql_library_end();});return true;};
 
 void
 MySqlHolder::setConnection(MYSQL* connection) {
+    // clear prepared statements associated to current connection
     clearPrepared();
+    // clear old database back-end object
     if (mysql_ != NULL) {
         mysql_close(mysql_);
     }
+    // set new database back-end object
     mysql_ = connection;
+    // clear connected flag
     connected_ = false;
+    // clear prepared flag
     prepared_ = false;
 }
 
@@ -52,20 +57,30 @@ MySqlHolder::clearPrepared() {
 
 void
 MySqlHolder::openDatabase(MySqlConnection& connection) {
+    // return if holder has already called openDatabase
     if (connected_) {
         return;
     }
+    // set connected flag
     connected_ = true;
+    // set prepared flag to true so that MySqlConnection::handle() within
+    // openDatabase function does not call prepareStatements before opening
+    // the new connection
     prepared_ = true;
+    // call openDatabase for this holder handle
     connection.openDatabase();
+    // set prepared flag to false so that MySqlConnection::handle() will
+    // call prepareStatements for this holder handle
     prepared_ = false;
 }
 
 void
 MySqlHolder::prepareStatements(MySqlConnection& connection) {
+    // return if holder has already called prepareStatemens
     if (prepared_) {
         return;
     }
+    // clear previous prepared statements
     clearPrepared();
     statements_.resize(connection.text_statements_.size(), NULL);
     uint32_t index = 0;
@@ -84,6 +99,7 @@ MySqlHolder::prepareStatements(MySqlConnection& connection) {
         }
         ++index;
     }
+    // set prepared flag
     prepared_ = true;
 }
 
diff --git a/src/lib/mysql/mysql_connection.h b/src/lib/mysql/mysql_connection.h
index 41da43ff31..2186802b09 100644
--- a/src/lib/mysql/mysql_connection.h
+++ b/src/lib/mysql/mysql_connection.h
@@ -94,26 +94,52 @@ class MySqlHolder : public boost::noncopyable {
 public:
     /// @brief Constructor
     ///
+    /// Sets the MySql API connector handle to NULL.
     /// Push a call to mysql_library_end() at exit time.
-    /// Initialize MySql and store the associated context object.
-    ///
-    /// @throw DbOpenError Unable to initialize MySql handle.
     MySqlHolder() : connected_(false), prepared_(false), mysql_(NULL) {
     }
 
     /// @brief Destructor
     ///
-    /// Frees up resources allocated by the initialization of MySql.
+    /// Frees up resources allocated by the connection holder.
     ~MySqlHolder() {
         clear();
         // @note Moved the call to mysql_library_end() to atexit.
     }
 
+    /// @brief Clear all resources
+    ///
+    /// Clear all resources.
+    void clear() {
+        setConnection(NULL);
+    }
+
+    /// @brief Clear prepared statements
+    ///
+    /// Clear prepared statements.
+    void clearPrepared();
+
     /// @brief Sets the connection to the value given
     ///
-    /// @param connection - pointer to the MYSQL connection instance
+    /// Sets the database back-end object.
+    ///
+    /// @param connection - pointer to the MySql connection instance
     void setConnection(MYSQL* connection);
 
+    /// @brief Open database
+    ///
+    /// Open database and apply MySql connection parameters.
+    ///
+    /// @param connection - associated connection which holds connection properties.
+    void openDatabase(MySqlConnection& connection);
+
+    /// @brief Prepare statements
+    ///
+    /// Prepare statements.
+    ///
+    /// @param connection - associated connection which holds the text statements.
+    void prepareStatements(MySqlConnection& connection);
+
     /// @brief Conversion Operator
     ///
     /// Allows the MySqlHolder object to be passed as the context argument to
@@ -122,29 +148,23 @@ public:
         return (mysql_);
     }
 
-    void clear() {
-        setConnection(NULL);
-    }
-
-    void clearPrepared();
-
-    void openDatabase(MySqlConnection& connection);
-
-    void prepareStatements(MySqlConnection& connection);
-
     /// @brief Prepared statements
     ///
     /// This field is public, because it is used heavily from MySqlConnection
     /// and from MySqlHostDataSource.
     std::vector<MYSQL_STMT*> statements_;
 
+    /// @brief The connected flag
     bool connected_;     ///< Flag to indicate openDatabase has been called
 
 private:
+    /// @brief The prepared flag
     bool prepared_;      ///< Flag to indicate prepareStatements has been called
 
+    /// @brief The atexit parameter called only once on initialization
     static bool atexit_; ///< Flag to call atexit once.
 
+    /// @brief The MySql database back-end object associated to this holder
     MYSQL* mysql_;       ///< Initialization context
 };