Db.h quick documentation

src/experimental/Db.h

@@ -13,24 +13,42 @@
 
 namespace experimental {
 
+/// SELF DOCUMENTING CODE
 using ColName = QString;
 using ColData = QString;
-using DataPosition = QPair<QString, int>;
+using TableName = QString;
+using RowId = int;
+using DataPosition = QPair<TableName, RowId>;
 using TableData = QMap<ColName, ColData>;
 
+// DEFAULTS
+auto const DEFAULT_PILOT_POSITION = DataPosition("pilots", 0);
+
+/*!
+ * \brief The Entry class encapsulates table metadata(table name, row id)
+ *  and data for new and existing entries in the database to operate on.
+ */
 class Entry {
 public:
     const DataPosition position;
-private:
+protected:
     TableData table_data;
 public:
     Entry() = delete;
-    Entry(DataPosition position_)
-        : position(position_) {}
+    Entry(DataPosition position_) : position(position_) {}
     void populate_data(TableData data) { table_data = data; }
     const TableData& data() { return table_data; }
 };
 
+// [George]: Either with polymorphism or simple functions the result will be the same.
+// if the following syntax is more clear to you we can switch to it.
+// ... = new NewPilotDialog(Pilot(selectedPilots.first(), ...);
+// the only difference will be that we will subclass Entry to have specialised
+// constructor
+class PilotEntry : public Entry {
+    PilotEntry() = delete;
+    PilotEntry(int row_id) : Entry::Entry(DataPosition("pilots", row_id)) {}
+};
 
 Entry newPilotEntry(int row_id) { return Entry(DataPosition("pilots", row_id)); }
 
@@ -39,20 +57,19 @@ bool insertPilot(UserInput& uin)
 {
     DEB("Inserting...");
     auto data = uin.all();
-    DataPosition position = DataPosition("pilots", 0);
+    auto position = DEFAULT_PILOT_POSITION;
 
     if (data.isEmpty()) {
         DEB("Object Contains no data. Aborting.");
         return false;
     }
     QString statement = "INSERT INTO " + position.first + QLatin1String(" (");
-    QMap<QString, QString>::const_iterator i;
-    for (i = data.cbegin(); i != data.cend(); ++i) {
+    for (auto i = data.cbegin(); i != data.cend(); ++i) {
         statement += i.key() + QLatin1String(", ");
     }
     statement.chop(2);
     statement += QLatin1String(") VALUES (");
-    for (i = data.cbegin(); i != data.cend(); ++i) {
+    for (auto i = data.cbegin(); i != data.cend(); ++i) {
         statement += QLatin1String("'") + i.value() + QLatin1String("', ");
     }
     statement.chop(2);
@@ -68,15 +85,22 @@ bool insertPilot(UserInput& uin)
     }
 }
 
+/*!
+ * \brief The DB class encapsulates the SQL database by providing fast access
+ * to hot database data.
+ */
 class DB {
 private:
     static QVector<QString> columns;
 public:
     /*!
-     * \brief init: Initialise DB class and populate columns.
+     * \brief Initialise DB class and populate columns.
      */
     static bool init();
 
+    /*!
+     * \brief Create new entry in the databse based on UserInput
+     */
     static
     bool insert(UserInput uin)
     {
@@ -97,13 +121,16 @@ public:
 
     static bool exists(UserInput uin) { return false; }
 
+    /*!
+     * \brief Updates entry in database from existing entry tweaked by the user.
+     * New entry data is verified before commiting.
+     */
     static bool update(Entry updated_entry)
     {
         auto position = updated_entry.position;
         auto data = updated_entry.data();
         QString statement = "UPDATE " + position.first + " SET ";
-        QMap<QString, QString>::const_iterator i;
-        for (i = data.constBegin(); i != data.constEnd(); ++i) {
+        for (auto i = data.constBegin(); i != data.constEnd(); ++i) {
             if (i.key() != QString()) {
                 statement += i.key() + QLatin1String("='") + i.value() + QLatin1String("', ");
             } else {
@@ -113,7 +140,6 @@ public:
         statement.chop(2); // Remove last comma
         statement.append(QLatin1String(" WHERE _rowid_=") + QString::number(position.second));
 
-        //execute query
         DEB("UPDATE QUERY: " << statement);
         QSqlQuery q(statement);
         //check result. Upon success, error should be " "
@@ -127,6 +153,9 @@ public:
         }
     }
 
+    /*!
+     * \brief Verify entry data is sane for the database.
+     */
     static
     bool verify(Entry entry)
     {