Doxygen-commenting models.py.

1 files changed, 48 insertions, 3 deletions

diff --git a/talerbank/app/models.py b/talerbank/app/models.py
index a125bd2..8df1fc6 100644
--- a/talerbank/app/models.py
+++ b/talerbank/app/models.py
@@ -27,17 +27,33 @@ from django.core.exceptions import \
     ObjectDoesNotExist
 from .amount import Amount, BadFormatAmount, CurrencyMismatch
 
+
+##
+# Helper function that instantiates a zero-valued @a Amount
+# object.
 def get_zero_amount() -> Amount:
     return Amount(settings.TALER_CURRENCY)
 
-class AmountField(models.Field):
 
+##
+# Custom implementation of the @a Amount class as a database type.
+class AmountField(models.Field):
     description = 'Amount object in Taler style'
 
+    ##
+    # Return the database type of the serialized amount.
+    #
+    # @param self the object itself.
+    # @param connection the database connection.
+    # @return type of the serialized amount: varchar.
     def db_type(self, connection: Any) -> str:
         return "varchar"
 
+    ##
     # Stringifies the Amount object to feed the DB connector.
+    #
+    # @param self the object itself.
+    # @para value the @a Amount object to be serialized.
     def get_prep_value(self, value: Amount) -> str:
         if not value:
             return "%s:0.0" % settings.TALER_CURRENCY
@@ -46,7 +62,13 @@ class AmountField(models.Field):
                                    value.currency)
         return value.stringify(settings.TALER_DIGITS)
 
+    ##
     # Parse the stringified Amount back to Python.
+    #
+    # @param value serialized amount coming from the database.
+    #        (It is just a string in the usual CURRENCY:X.Y form)
+    # @param args currently unused.
+    # @return the @a Amount object.
     @staticmethod
     def from_db_value(value: str, *args) -> Amount:
         del args # pacify PEP checkers
@@ -54,8 +76,16 @@ class AmountField(models.Field):
             return Amount.parse(settings.TALER_CURRENCY)
         return Amount.parse(value)
 
-    # Parse the stringified Amount back to Python (considering
-    # some more cases.)
+
+    ##
+    # Parse the stringified Amount back to Python. FIXME:
+    # why this serializer consider _more_ cases respect to the
+    # one above ('from_db_value')?
+    #
+    # @param value serialized amount coming from the database.
+    #        (It is just a string in the usual CURRENCY:X.Y form)
+    # @param args currently unused.
+    # @return the @a Amount object.
     def to_python(self, value: Any) -> Amount:
         if isinstance(value, Amount):
             return value
@@ -67,14 +97,26 @@ class AmountField(models.Field):
             raise ValidationError(
                 "Invalid input for an amount string: %s" % value)
 
+
+##
+# Exception class to raise when a non-existent bank account is
+# tried to be referenced.
 class BankAccountDoesNotExist(ObjectDoesNotExist):
     hint = "Specified bank account does not exist"
     http_status_code = 404
 
+
+##
+# Exception class to raise when a non-existent bank transaction is
+# tried to be referenced.
 class BankTransactionDoesNotExist(ObjectDoesNotExist):
     hint = "Specified bank transaction does not exist"
     http_status_code = 404
 
+
+
+##
+# The class representing a bank account.
 class BankAccount(models.Model):
     is_public = models.BooleanField(default=False)
     debit = models.BooleanField(default=False)
@@ -83,6 +125,9 @@ class BankAccount(models.Model):
     amount = AmountField(default=get_zero_amount)
     DoesNotExist = BankAccountDoesNotExist
 
+
+##
+# The class representing a bank transaction.
 class BankTransaction(models.Model):
     amount = AmountField(default=False)
     debit_account = models.ForeignKey(