Add comments

src/tribler/core/upgrade/tribler_db/conftest.py

@@ -11,6 +11,7 @@
 
 @pytest.fixture
 def migration_chain(tmpdir):
+    """ Create an empty migration chain with an empty database."""
     db_file_name = Path(tmpdir) / STATEDIR_DB_DIR / 'tribler.db'
     db_file_name.parent.mkdir()
     TriblerDatabase(filename=str(db_file_name))

src/tribler/core/upgrade/tribler_db/decorator.py

@@ -7,11 +7,22 @@
 
 MIGRATION_METADATA = "_tribler_db_migration"
 
-logger = logging.getLogger('Migration: TriblerDB')
+logger = logging.getLogger('Migration (TriblerDB)')
 
 
 def migration(execute_only_if_version: Optional[int] = None,
               set_after_successful_execution_version: Optional[int] = None):
+    """ Decorator for migration functions.
+
+    The migration executes in the single transaction. If the migration fails, the transaction is rolled back.
+    The decorator also sets the metadata attribute to the decorated function. It could be checked by
+    calling the `has_migration_metadata` function.
+
+    Args:
+        execute_only_if_version: Execute the migration only if the current db version is equal to this value.
+        set_after_successful_execution_version: Set the db version to this value after the migration is executed.
+    """
+
     def decorator(func):
         @functools.wraps(func)
         @db_session
@@ -38,4 +49,5 @@ def wrapper(db: TriblerDatabase, **kwargs):
 
 
 def has_migration_metadata(f: Callable):
+    """ Check if the function has migration metadata."""
     return hasattr(f, MIGRATION_METADATA)

src/tribler/core/upgrade/tribler_db/migration_chain.py

@@ -1,5 +1,5 @@
 import logging
-from typing import Callable, Iterable, Iterator, List, Optional
+from typing import Callable, Iterator, List, Optional
 
 from tribler.core.components.database.db.tribler_database import TriblerDatabase
 from tribler.core.upgrade.tribler_db.decorator import has_migration_metadata
@@ -9,6 +9,12 @@
 
 
 class TriblerDatabaseMigrationChain:
+    """ A chain of migrations that can be executed on a TriblerDatabase.
+
+    To create a new migration, create a new function and decorate it with the `migration` decorator. Then add it to
+    the `DEFAULT_CHAIN` list.
+    """
+
     DEFAULT_CHAIN = [
         scheme_migration_0,
         # add your migration here
@@ -25,6 +31,12 @@ def __init__(self, state_dir: Path, chain: Optional[List[Callable]] = None):
         self.migrations = chain or self.DEFAULT_CHAIN
 
     def execute(self) -> bool:
+        """ Execute all migrations in the chain.
+
+        Returns: True if all migrations were executed successfully, False otherwise.
+        An exception in any of the migrations will halt the execution chain and be re-raised.
+        """
+
         if not self.db:
             return False
 
@@ -34,8 +46,8 @@ def execute(self) -> bool:
         return True
 
     def steps(self) -> Iterator:
+        """ Execute migrations step by step."""
         for m in self.migrations:
             if not has_migration_metadata(m):
                 raise NotImplementedError(f'The migration {m} should have `migration` decorator')
             yield m(self.db, state_dir=self.state_dir)
-