Merge pull request #377 Some documentation fixes from cbielow/fix_doc

Author: SRombauts

Doxyfile

@@ -193,6 +193,17 @@ cmake --build .
 ctest --output-on-failure
 ```
 
+#### Building the Doxygen/html documentation
+
+Make sure you have Dogygen installed and configure CMake using the `SQLITECPP_RUN_DOXYGEN=ON` flag:
+
+```
+cmake -DSQLITECPP_RUN_DOXYGEN=ON   <MORE ARGUMENTS_HERE>
+```
+
+and then execute the `SQLiteCpp_doxygen` target (or build all targets, see above).
+The documentation will be generated in the 'doc' subfolder of the source tree.
+
 #### CMake options
 
   * For more options on customizing the build, see the [CMakeLists.txt](https://github.com/SRombauts/SQLiteCpp/blob/master/CMakeLists.txt) file.

README.md

@@ -31,7 +31,7 @@ extern const int Null;      ///< SQLITE_NULL
 /**
  * @brief Encapsulation of a Column in a row of the result pointed by the prepared Statement.
  *
- *  A Column is a particular field of SQLite data in the current row of result
+ * A Column is a particular field of SQLite data in the current row of result
  * of the Statement : it points to a single cell.
  *
  * Its value can be expressed as a text, and, when applicable, as a numeric
@@ -103,9 +103,12 @@ class Column
     std::string getString() const;
 
     /**
-     * @brief Return the type of the value of the column
+     * @brief Return the type of the value of the column using sqlite3_column_type()
      *
      * Return either SQLite::INTEGER, SQLite::FLOAT, SQLite::TEXT, SQLite::BLOB, or SQLite::Null.
+     * This type may change from one row to the next, since
+     * SQLite stores data types dynamically for each value and not per column.
+     * Use Statement::getColumnDeclaredType() to retrieve the declared column type from a SELECT statement.
      *
      * @warning After a type conversion (by a call to a getXxx on a Column of a Yyy type),
      *          the value returned by sqlite3_column_type() is undefined.

include/SQLiteCpp/Column.h

@@ -256,8 +256,8 @@ class Database
      * @brief Set a busy handler that sleeps for a specified amount of time when a table is locked.
      *
      *  This is useful in multithreaded program to handle case where a table is locked for writing by a thread.
-     * Any other thread cannot access the table and will receive a SQLITE_BUSY error:
-     * setting a timeout will wait and retry up to the time specified before returning this SQLITE_BUSY error.
+     *  Any other thread cannot access the table and will receive a SQLITE_BUSY error:
+     *  setting a timeout will wait and retry up to the time specified before returning this SQLITE_BUSY error.
      *  Reading the value of timeout for current connection can be done with SQL query "PRAGMA busy_timeout;".
      *  Default busy timeout is 0ms.
      *
@@ -322,7 +322,7 @@ class Database
      *
      * @see exec() to execute, returning number of rows modified
      *
-     * @param[in] aQueries  one or multiple UTF-8 encoded, semicolon-separate SQL statements
+     * @param[in] apQueries  one or multiple UTF-8 encoded, semicolon-separate SQL statements
      *
      * @return the sqlite result code.
      */
@@ -424,7 +424,7 @@ class Database
     /**
      * @brief Get the rowid of the most recent successful INSERT into the database from the current connection.
      *
-     *  Each entry in an SQLite table always has a unique 64-bit signed integer key called the rowid.
+     * Each entry in an SQLite table always has a unique 64-bit signed integer key called the rowid.
      * If the table has a column of type INTEGER PRIMARY KEY, then it is an alias for the rowid.
      *
      * @return Rowid of the most recent successful INSERT into the database, or 0 if there was none.

include/SQLiteCpp/Database.h

@@ -23,7 +23,7 @@ class Database;
  * @brief RAII encapsulation of a SQLite Savepoint.
  *
  * A Savepoint is a way to group multiple SQL statements into an atomic
- * secureced operation; either it succeeds, with all the changes commited to the
+ * secure operation; either it succeeds, with all the changes committed to the
  * database file, or if it fails, all the changes are rolled back to the initial
  * state at the start of the savepoint.
  *
@@ -39,7 +39,7 @@ class Database;
  * savepoint to be rolled back.
  *
  * 3) This savepoint is not saved to the database until this and all savepoints
- * or transaction in the savepoint stack have been released or commited.
+ * or transaction in the savepoint stack have been released or committed.
  *
  * See also: https://sqlite.org/lang_savepoint.html
  *
@@ -66,7 +66,7 @@ class Savepoint {
      * Exception is thrown in case of error, then the Savepoint is NOT
      * initiated.
      */
-    Savepoint(Database& aDatabase, const std::string& name);
+    Savepoint(Database& aDatabase, const std::string& aName);
 
     // Savepoint is non-copyable
     Savepoint(const Savepoint&) = delete;

include/SQLiteCpp/Savepoint.h

@@ -86,7 +86,10 @@ class Statement
     /// The finalization will be done by the destructor of the last shared pointer
     ~Statement() = default;
 
-    /// Reset the statement to make it ready for a new execution. Throws an exception on error.
+    /// Reset the statement to make it ready for a new execution by calling sqlite3_reset.
+    /// Throws an exception on error.
+    /// Call this function before any news calls to bind() if the statement was already executed before.
+    /// Calling reset() does not clear the bindings (see clearBindings()).
     void reset();
 
     /// Reset the statement. Returns the sqlite result code instead of throwing an exception on error.

include/SQLiteCpp/Statement.h

@@ -38,7 +38,7 @@ enum class TransactionBehavior {
  * or if it fails, all the changes are rolled back to the initial state.
  *
  * Resource Acquisition Is Initialization (RAII) means that the Transaction
- * begins in the constructor and is rollbacked in the destructor, so that there is
+ * begins in the constructor and is rolled back in the destructor (unless comitted before), so that there is
  * no need to worry about memory management or the validity of the underlying SQLite Connection.
  *
  * This method also offers big performances improvements compared to individually executed statements.

include/SQLiteCpp/Transaction.h

@@ -92,19 +92,7 @@ void Database::Deleter::operator()(sqlite3* apSQLite)
     SQLITECPP_ASSERT(SQLITE_OK == ret, "database is locked");  // See SQLITECPP_ENABLE_ASSERT_HANDLER
 }
 
-/**
- * @brief Set a busy handler that sleeps for a specified amount of time when a table is locked.
- *
- *  This is useful in multithreaded program to handle case where a table is locked for writting by a thread.
- *  Any other thread cannot access the table and will receive a SQLITE_BUSY error:
- *  setting a timeout will wait and retry up to the time specified before returning this SQLITE_BUSY error.
- *  Reading the value of timeout for current connection can be done with SQL query "PRAGMA busy_timeout;".
- *  Default busy timeout is 0ms.
- *
- * @param[in] aBusyTimeoutMs    Amount of milliseconds to wait before returning SQLITE_BUSY
- *
- * @throw SQLite::Exception in case of error
- */
+//Set a busy handler that sleeps for a specified amount of time when a table is locked.
 void Database::setBusyTimeout(const int aBusyTimeoutMs)
 {
     const int ret = sqlite3_busy_timeout(getHandle(), aBusyTimeoutMs);

src/Database.cpp

@@ -43,7 +43,7 @@ Statement::Statement(Statement&& aStatement) noexcept :
     aStatement.mbDone = false;
 }
 
-// Reset the statement to make it ready for a new execution (see also #clearBindings() bellow)
+// Reset the statement to make it ready for a new execution (see also #clearBindings() below)
 void Statement::reset()
 {
     const int ret = tryReset();