SchemaManager: Add documentation comments

res/schema.xml

@@ -148,7 +148,7 @@ METADATA
   </revision>
   <revision version="6">
     <description>
-                    Added a ReplayGain Column.
+      Added a ReplayGain Column.
     </description>
     <sql>
         ALTER TABLE library ADD COLUMN replaygain float DEFAULT 0;
@@ -490,8 +490,7 @@ METADATA
       <!-- White -->
       UPDATE cues SET color=0xF2F2FF WHERE color=8;
       <!-- Remove alpha channel from cues that were updated by
-           previous, in-development schema migrations
-        -->
+           previous, in-development schema migrations -->
       UPDATE cues SET color = (color &amp; 0xFFFFFF) WHERE color > 0xFFFFFF;
     </sql>
   </revision>

src/database/schemamanager.cpp

@@ -43,24 +43,10 @@ bool SchemaManager::isBackwardsCompatibleWithVersion(int targetVersion) const {
     bool ok = false;
     int iBackwardsCompatibleVersion = backwardsCompatibleVersion.toInt(&ok);
 
-    // If the current backwards compatible schema version is not stored in the
-    // settings table, assume the current schema version is only backwards
-    // compatible with itself.
     if (backwardsCompatibleVersion.isNull() || !ok) {
-        // rryan 11/2010 We just added the backwards compatible flags, and some
-        // people using the Mixxx trunk are already on schema version 7. This
-        // special case is for them. Schema version 7 is backwards compatible
-        // with schema version 3.
-        if (m_currentVersion == 7) {
-            iBackwardsCompatibleVersion = 3;
-        } else {
-            iBackwardsCompatibleVersion = m_currentVersion;
-        }
+        iBackwardsCompatibleVersion = m_currentVersion;
     }
 
-    // If the target version is greater than the minimum compatible version of
-    // the current schema, then the current schema is backwards compatible with
-    // targetVersion.
     return iBackwardsCompatibleVersion <= targetVersion;
 }
 
@@ -76,12 +62,7 @@ SchemaManager::Result SchemaManager::upgradeToSchemaVersion(
                 << "Database schema is up-to-date"
                 << "at version" << m_currentVersion;
         return Result::CurrentVersion;
-    } else if (m_currentVersion < targetVersion) {
-        kLogger.info()
-                << "Upgrading database schema"
-                << "from version" << m_currentVersion
-                << "to version" << targetVersion;
-    } else {
+    } else if (m_currentVersion > targetVersion) {
         if (isBackwardsCompatibleWithVersion(targetVersion)) {
             kLogger.info()
                     << "Current database schema is newer"
@@ -98,6 +79,10 @@ SchemaManager::Result SchemaManager::upgradeToSchemaVersion(
             return Result::NewerVersionIncompatible;
         }
     }
+    kLogger.info()
+            << "Upgrading database schema"
+            << "from version" << m_currentVersion
+            << "to version" << targetVersion;
 
     if (kLogger.debugEnabled()) {
         kLogger.debug()
@@ -129,14 +114,11 @@ SchemaManager::Result SchemaManager::upgradeToSchemaVersion(
         revisionMap[iVersion] = revision;
     }
 
-    // The checks above guarantee that currentVersion < targetVersion when we
-    // get here.
     while (m_currentVersion < targetVersion) {
         int nextVersion = m_currentVersion + 1;
 
-        // Now that we bake the schema.xml into the binary it is a programming
-        // error if we include a schema.xml that does not have information on
-        // how to get all the way to targetVersion.
+        // With the packaged schema.xml it is an error if it does not have
+        // information on how to get all the way to targetVersion.
         VERIFY_OR_DEBUG_ASSERT(revisionMap.contains(nextVersion)) {
             kLogger.critical()
                      << "Migration path for upgrading database schema"
@@ -149,8 +131,8 @@ SchemaManager::Result SchemaManager::upgradeToSchemaVersion(
         QDomElement revision = revisionMap[nextVersion];
         QDomElement eDescription = revision.firstChildElement("description");
         QDomElement eSql = revision.firstChildElement("sql");
-        QString minCompatibleVersion = revision.attribute("min_compatible");
 
+        QString minCompatibleVersion = revision.attribute("min_compatible");
         // Default the min-compatible version to the current version string if
         // it's not in the schema.xml
         if (minCompatibleVersion.isNull()) {
@@ -168,7 +150,7 @@ SchemaManager::Result SchemaManager::upgradeToSchemaVersion(
         QString sql = eSql.text();
 
         kLogger.info()
-                << "Upgrading to database schema to version"
+                << "Upgrading database schema to version"
                 << nextVersion << ":"
                 << description.trimmed();
 
@@ -196,11 +178,11 @@ SchemaManager::Result SchemaManager::upgradeToSchemaVersion(
                 // New columns may have already been added during a previous
                 // migration to a different (= preceding) schema version. This
                 // is a very common situation during development when switching
-                // between schema versions. Since SQLite does not allow to add
-                // new columns only if they do not yet exist we need to account
-                // for and handle those errors here after they occurred. If the
-                // remaining migration finishes without other errors this is
-                // probably ok.
+                // between schema versions. Since SQLite only allows to add new
+                // columns if they do not yet exist, we need to account for and
+                // handle those errors here after they occurred.
+                // If the remaining migration finishes without other errors this
+                // is probably ok.
                 kLogger.warning()
                         << "Ignoring failed statement"
                         << statement

src/database/schemamanager.h

@@ -1,11 +1,14 @@
-#ifndef SCHEMAMANAGER_H
-#define SCHEMAMANAGER_H
+#pragma once
 
 #include <QSqlDatabase>
 
 #include "preferences/usersettings.h"
 #include "library/dao/settingsdao.h"
 
+/// The SchemaManager reads the database schema from the schemaFile
+/// (res/schema.xml in development) and is responsible for checking
+/// compatibility as well as upgrading the database if necessary.
+/// It also caches some information about the current version in a SettingsDAO.
 class SchemaManager {
   public:
     static const QString SETTINGS_VERSION_STRING;
@@ -26,8 +29,18 @@ class SchemaManager {
         return m_currentVersion;
     }
 
+    /// Check if the current version is backwards compatible with the given targetVersion.
+    ///
+    /// If the current version has no backwards compatibility info, it is
+    /// assumed that it is only compatible with itself.
+    ///
+    /// Returns true if the targetVersion is greater or equal to the
+    /// minimum compatible version of the current schema
     bool isBackwardsCompatibleWithVersion(int targetVersion) const;
 
+    /// Tries to upgrade the database schema to the given targetVersion.
+    /// First checks for version compatibility and whether the current version
+    /// already suffices the target and potentially aborts with the appropriate Result.
     Result upgradeToSchemaVersion(
             const QString& schemaFilename,
             int targetVersion);
@@ -38,5 +51,3 @@ class SchemaManager {
 
     int m_currentVersion;
 };
-
-#endif /* SCHEMAMANAGER_H */