From 7a8c898ebc822b44591adb946f630c7bb51e177f Mon Sep 17 00:00:00 2001
From: s3lph <account-gitlab-ideynizv@kernelpanic.lol>
Date: Wed, 6 Jun 2018 14:13:42 +0200
Subject: [PATCH] Added additional documentation to MatematDatabase.

---
 matemat/db/facade.py | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/matemat/db/facade.py b/matemat/db/facade.py
index 7df896a..f91bf4a 100644
--- a/matemat/db/facade.py
+++ b/matemat/db/facade.py
@@ -328,10 +328,11 @@ class MatematDatabase(object):
         the statistics table.
         :param user: The user buying a product.
         :param product: The product the user is buying.
-        :param count: How many instances of the product the user is buying, defaults to 1.
+        :param count: How many units of the product the user is buying, defaults to 1.
         :raises DatabaseConsistencyError: If the user or the product does not exist in the database.
         """
         with self.db.transaction() as c:
+            # Retrieve the consumption entry for the (user, product) pair, if any.
             c.execute('''
             SELECT count
             FROM consumption
@@ -343,6 +344,7 @@ class MatematDatabase(object):
             })
             row = c.fetchone()
             if row is None:
+                # If the entry does not exist, create a new one.
                 c.execute('''
                 INSERT INTO consumption (user_id, product_id, count)
                 VALUES (:user_id, :product_id, :count)
@@ -352,6 +354,7 @@ class MatematDatabase(object):
                     'count': count
                 })
             else:
+                # If the entry exists, update the consumption count.
                 c.execute('''
                 UPDATE consumption
                 SET count = count + :count
@@ -361,10 +364,12 @@ class MatematDatabase(object):
                     'product_id': product.id,
                     'count': count
                 })
+            # Make sure exactly one consumption row was updated/inserted.
             affected = c.execute('SELECT changes()').fetchone()[0]
             if affected != 1:
                 raise DatabaseConsistencyError(
                     f'increment_consumption should affect 1 consumption row, but affected {affected}')
+            # Compute the cost of the transaction and subtract it from the user's account balance.
             c.execute('''
             UPDATE users
             SET balance = balance - :cost
@@ -372,10 +377,12 @@ class MatematDatabase(object):
                 'user_id': user.id,
                 'cost': count * product.price_member if user.is_member else count * product.price_non_member
             })
+            # Make sure exactly one user row was updated.
             affected = c.execute('SELECT changes()').fetchone()[0]
             if affected != 1:
                 raise DatabaseConsistencyError(
                     f'increment_consumption should affect 1 users row, but affected {affected}')
+            # Subtract the number of purchased units from the product's stock.
             c.execute('''
             UPDATE products
             SET stock = stock - :count
@@ -384,6 +391,7 @@ class MatematDatabase(object):
                 'product_id': product.id,
                 'count': count
             })
+            # Make sure exactly one product row was updated.
             affected = c.execute('SELECT changes()').fetchone()[0]
             if affected != 1:
                 raise DatabaseConsistencyError(
@@ -393,7 +401,7 @@ class MatematDatabase(object):
         """
         Update the stock of a product.
         :param product: The product to restock.
-        :param count: Number of instances of the product to add.
+        :param count: Number of units of the product to add.
         :raises DatabaseConsistencyError: If the product represented by the object does not exist.
         """
         with self.db.transaction() as c: