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

[#888,!573] updated doxygen
---

diff --git a/src/lib/pgsql/pgsql_connection.cc b/src/lib/pgsql/pgsql_connection.cc
index b33a7334aa..7ce1f7e537 100644
--- a/src/lib/pgsql/pgsql_connection.cc
+++ b/src/lib/pgsql/pgsql_connection.cc
@@ -39,25 +39,30 @@ const char PgSqlConnection::DUPLICATE_KEY[] = ERRCODE_UNIQUE_VIOLATION;
 
 void
 PgSqlHolder::setConnection(PGconn* connection) {
+    // clear prepared statements associated to current connection
     clearPrepared();
-    if (pgconn_ != NULL) {
-        PQfinish(pgconn_);
+    // clear old database back-end object
+    if (pgsql_ != NULL) {
+        PQfinish(pgsql_);
     }
-    pgconn_ = connection;
+    // set new database back-end object
+    pgsql_ = connection;
+    // clear connected flag
     connected_ = false;
+    // clear prepared flag
     prepared_ = false;
 }
 
 void
 PgSqlHolder::clearPrepared() {
-    if (pgconn_ != NULL) {
+    if (pgsql_ != NULL) {
         // Deallocate the prepared queries.
-        if (PQstatus(pgconn_) == CONNECTION_OK) {
-            PgSqlResult r(PQexec(pgconn_, "DEALLOCATE all"));
+        if (PQstatus(pgsql_) == CONNECTION_OK) {
+            PgSqlResult r(PQexec(pgsql_, "DEALLOCATE all"));
             if(PQresultStatus(r) != PGRES_COMMAND_OK) {
                 // Highly unlikely but we'll log it and go on.
                 DB_LOG_ERROR(PGSQL_DEALLOC_ERROR)
-                    .arg(PQerrorMessage(pgconn_));
+                    .arg(PQerrorMessage(pgsql_));
             }
         }
     }
@@ -65,31 +70,42 @@ PgSqlHolder::clearPrepared() {
 
 void
 PgSqlHolder::openDatabase(PgSqlConnection& connection) {
+    // return if holder has already called openDatabase
     if (connected_) {
         return;
     }
+    // set connected flag
     connected_ = true;
+    // set prepared flag to true so that PgSqlConnection::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 PgSqlConnection::handle() will
+    // call prepareStatements for this holder handle
     prepared_ = false;
 }
 
 void
 PgSqlHolder::prepareStatements(PgSqlConnection& connection) {
+    // return if holder has already called prepareStatemens
     if (prepared_) {
         return;
     }
+    // clear previous prepared statements
     clearPrepared();
     // Prepare all statements queries with all known fields datatype
     for (auto it = connection.statements_.begin();
         it != connection.statements_.end(); ++it) {
-        PgSqlResult r(PQprepare(pgconn_, (*it)->name, (*it)->text,
+        PgSqlResult r(PQprepare(pgsql_, (*it)->name, (*it)->text,
                                 (*it)->nbparams, (*it)->types));
         if (PQresultStatus(r) != PGRES_COMMAND_OK) {
             isc_throw(DbOperationError, "unable to prepare PostgreSQL statement: "
-                      << (*it)->text << ", reason: " << PQerrorMessage(pgconn_));
+                      << (*it)->text << ", reason: " << PQerrorMessage(pgsql_));
         }
     }
+    // set prepared flag
     prepared_ = true;
 }
 
diff --git a/src/lib/pgsql/pgsql_connection.h b/src/lib/pgsql/pgsql_connection.h
index 40dd05df6f..bb60c93e57 100644
--- a/src/lib/pgsql/pgsql_connection.h
+++ b/src/lib/pgsql/pgsql_connection.h
@@ -184,31 +184,48 @@ class PgSqlHolder : public boost::noncopyable {
 public:
     /// @brief Constructor
     ///
-    /// Sets the Postgresql API connector handle to NULL.
-    ///
-    PgSqlHolder() : connected_(false), prepared_(false), pgconn_(NULL) {
+    /// Sets the PgSql API connector handle to NULL.
+    PgSqlHolder() : connected_(false), prepared_(false), pgsql_(NULL) {
     }
 
     /// @brief Destructor
     ///
-    /// Frees up resources allocated by the connection.
+    /// Frees up resources allocated by the connection holder.
     ~PgSqlHolder() {
         clear();
     }
 
+    /// @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 Postgresql connection instance
+    /// Sets the database back-end object.
+    ///
+    /// @param connection - pointer to the PgSql connection instance
     void setConnection(PGconn* connection);
 
+    /// @brief Open database
+    ///
+    /// Open database and apply PgSql connection parameters.
+    ///
+    /// @param connection - associated connection which holds connection properties.
     void openDatabase(PgSqlConnection& connection);
 
+    /// @brief Prepare statements
+    ///
+    /// Prepare statements.
+    ///
+    /// @param connection - associated connection which holds the text statements.
     void prepareStatements(PgSqlConnection& connection);
 
     /// @brief Conversion Operator
@@ -216,15 +233,18 @@ public:
     /// Allows the PgSqlHolder object to be passed as the context argument to
     /// PQxxxx functions.
     operator PGconn*() const {
-        return (pgconn_);
+        return (pgsql_);
     }
 
+    /// @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
 
-    PGconn* pgconn_;     ///< Postgresql connection
+    /// @brief The PgSql database back-end object associated to this holder
+    PGconn* pgsql_;     ///< Postgresql connection
 };
 
 /// @brief RAII object representing a PostgreSQL transaction.