Add some comments

lib/src/HttpServer.cc

@@ -67,7 +67,7 @@ HttpServer::~HttpServer()
 
 void HttpServer::start()
 {
-    LOG_WARN << "HttpServer[" << _server.name()
+    LOG_TRACE << "HttpServer[" << _server.name()
              << "] starts listenning on " << _server.ipPort();
     _server.start();
 }

orm_lib/inc/drogon/orm/Field.h

@@ -80,12 +80,33 @@ namespace drogon
 {
 namespace orm
 {
+
+/// Reference to a field in a result set.
+/** 
+ * A field represents one entry in a row.  It represents an actual value
+ * in the result set, and can be converted to various types.
+ */
 class Field
 {
   public:
     using size_type = unsigned long;
+
+    /// Column name
     const char *name() const;
+
+    /// Is this field's value null?
     bool isNull() const;
+
+    /// Read as plain C string
+    /** 
+     * Since the field's data is stored internally in the form of a
+     * zero-terminated C string, this is the fastest way to read it.  Use the
+     * to() or as() functions to convert the string to other types such as
+     * @c int, or to C++ strings.
+     */
+    const char *c_str() const;
+
+    /// Convert to a type T value
     template <typename T>
     T as() const
     {
@@ -115,6 +136,15 @@ class Field
         }
         return value;
     }
+
+    /// Parse the field as an SQL array.
+    /** 
+     * Call the parser to retrieve values (and structure) from the array.
+     *
+     * Make sure the @c result object stays alive until parsing is finished.  If
+     * you keep the @c row of @c field object alive, it will keep the @c result
+     * object alive as well.
+     */
     ArrayParser getArrayParser() const
     {
         return ArrayParser(_result.getValue(_row, _column));

orm_lib/inc/drogon/orm/Result.h

@@ -37,6 +37,21 @@ enum class SqlStatus
     Ok,
     End
 };
+
+/// Result set containing data returned by a query or command.
+/** This behaves as a container (as defined by the C++ standard library) and
+ * provides random access const iterators to iterate over its rows.  A row
+ * can also be accessed by indexing a result R by the row's zero-based
+ * number:
+ *
+ * @code
+ *	for (result::size_type i=0; i < R.size(); ++i) Process(R[i]);
+ * @endcode
+ *
+ * Result sets in libpqxx are lightweight, reference-counted wrapper objects
+ * which are relatively small and cheap to copy.  Think of a result object as
+ * a "smart pointer" to an underlying result set.
+ */
 class Result
 {
   public:
@@ -73,15 +88,24 @@ class Result
     reference operator[](size_type index) const;
     reference at(size_type index) const;
     void swap(Result &) noexcept;
+
+    /// Number of columns in result.
     row_size_type columns() const noexcept;
+
     /// Name of column with this number (throws exception if it doesn't exist)
     const char *columnName(row_size_type number) const;
 
+    /// If command was @c INSERT, @c UPDATE, or @c DELETE: number of affected rows
+    /**
+     * @return Number of affected rows if last command was @c INSERT, @c UPDATE,
+     * or @c DELETE; zero for all other commands.
+     */
     size_type affectedRows() const noexcept;
 
     /// For Mysql, Sqlite3 database
     unsigned long long insertId() const noexcept;
 
+    /// Query that produced this result, if available (empty string otherwise)
     const std::string &sql() const noexcept;
 
   private:

orm_lib/inc/drogon/orm/Row.h

@@ -28,6 +28,19 @@ class Field;
 class ConstRowIterator;
 class ConstReverseRowIterator;
 
+/// Reference to one row in a result.
+/** 
+ * A row represents one row (also called a row) in a query result set.
+ * It also acts as a container mapping column numbers or names to field
+ * values (see below):
+ *
+ * @code
+ *	cout << row["date"].as<std::string>() << ": " << row["name"].as<std::string>() << endl;
+ * @endcode
+ *
+ * The row itself acts like a (non-modifyable) container, complete with its
+ * own const_iterator and const_reverse_iterator.
+ */
 class Row
 {
   public:

orm_lib/src/DbClientLockFree.cc

@@ -70,20 +70,6 @@ DbClientLockFree::~DbClientLockFree() noexcept
     }
 }
 
-void DbClientLockFree::execSql(const DbConnectionPtr &conn,
-                               std::string &&sql,
-                               size_t paraNum,
-                               std::vector<const char *> &&parameters,
-                               std::vector<int> &&length,
-                               std::vector<int> &&format,
-                               ResultCallback &&rcb,
-                               std::function<void(const std::exception_ptr &)> &&exceptCallback)
-{
-    assert(conn);
-    std::weak_ptr<DbConnection> weakConn = conn;
-    conn->execSql(std::move(sql), paraNum, std::move(parameters), std::move(length), std::move(format),
-                  std::move(rcb), std::move(exceptCallback));
-}
 void DbClientLockFree::execSql(std::string &&sql,
                                size_t paraNum,
                                std::vector<const char *> &&parameters,
@@ -113,14 +99,13 @@ void DbClientLockFree::execSql(std::string &&sql,
     {
         if (!_connection->isWorking())
         {
-            execSql(_connection,
-                    std::move(sql),
-                    paraNum,
-                    std::move(parameters),
-                    std::move(length),
-                    std::move(format),
-                    std::move(rcb),
-                    std::move(exceptCallback));
+            _connection->execSql(std::move(sql),
+                                 paraNum,
+                                 std::move(parameters),
+                                 std::move(length),
+                                 std::move(format),
+                                 std::move(rcb),
+                                 std::move(exceptCallback));
             return;
         }
     }
@@ -163,14 +148,13 @@ void DbClientLockFree::handleNewTask()
     if (!_sqlCmdBuffer.empty())
     {
         auto &cmd = _sqlCmdBuffer.front();
-        execSql(_connection,
-                std::move(cmd._sql),
-                cmd._paraNum,
-                std::move(cmd._parameters),
-                std::move(cmd._length),
-                std::move(cmd._format),
-                std::move(cmd._cb),
-                std::move(cmd._exceptCb));
+        _connection->execSql(std::move(cmd._sql),
+                             cmd._paraNum,
+                             std::move(cmd._parameters),
+                             std::move(cmd._length),
+                             std::move(cmd._format),
+                             std::move(cmd._cb),
+                             std::move(cmd._exceptCb));
         _sqlCmdBuffer.pop_front();
         return;
     }

orm_lib/src/DbClientLockFree.h

@@ -47,21 +47,9 @@ class DbClientLockFree : public DbClient, public std::enable_shared_from_this<Db
   private:
     std::string _connInfo;
     trantor::EventLoop *_loop;
-
-    void execSql(const DbConnectionPtr &conn,
-                 std::string &&sql,
-                 size_t paraNum,
-                 std::vector<const char *> &&parameters,
-                 std::vector<int> &&length,
-                 std::vector<int> &&format,
-                 ResultCallback &&rcb,
-                 std::function<void(const std::exception_ptr &)> &&exceptCallback);
-
     DbConnectionPtr newConnection();
-
     DbConnectionPtr _connection;
     DbConnectionPtr _connectionHolder;
-
     struct SqlCmd
     {
         std::string _sql;

orm_lib/src/Field.cc

@@ -60,6 +60,11 @@ std::vector<char> Field::as<std::vector<char>>() const
     char *last = first + _result.getLength(_row, _column);
     return std::vector<char>(first, last);
 }
+
+const char *Field::c_str() const
+{
+    return as<const char *>();
+}
 // template <>
 // std::vector<short> Field::as<std::vector<short>>() const
 // {