add docu, refractor

coinmanager/coinc/models.py

@@ -28,10 +28,14 @@ year_now        = int(datetime.now().year)
 
 
 class User(Model):
+
+    ## id: Set automatically, only used by django
     id              = BigAutoField(primary_key=True)
 
+    ## name: The name of a *User*
     name            = CharField('Name', max_length=20, default='Anonym')
 
+    ## color: The desired color of a *User*
     color           = CharField('Farbe', max_length=20, default='purple')
 
 
@@ -41,14 +45,20 @@ class User(Model):
 
 
 class Country(Model):
+
+    ## name_iso: The "ISO 3166 ALPHA-2" country code of a *Country*
+    ## Note: This field is unique and serves also as primary key
     name_iso        = CharField('Kürzel', max_length=2, primary_key=True)
 
+    ## name: The actual name of a *Country*
     name            = CharField('Land', max_length=50)
 
-    comment         = TextField('Kommentar', default='', blank=True)
+    ## euro_member_since: The year [YYYY] since when a *Country* stamps Euros
-
     euro_member_since      = PositiveSmallIntegerField('Währungsmitglied seit', default=year_now)
 
+    ## comment: Any comment concerning a *Country*
+    comment         = TextField('Kommentar', default='', blank=True)
+
 
     def __str__(self):
         return f"{self.name}"
@@ -56,16 +66,25 @@ class Country(Model):
 
 
 class Stamp(Model):
+
+    ## name_short: An abbreviation for the stamp of the coin
+    ## Note: This field is unique and serves also as primary key
     name_short      = CharField('Prägung', max_length=10, primary_key=True)
 
+    ## name: The actual name a *Stamp*
     name            = CharField('Name', max_length=50)
 
+    ## country: References a *Country* to which a *Stamp* belongs to
+    ## Possible values: ANY pre-defined *Country*
+    country         = ForeignKey('Country', on_delete=CASCADE, null=True, blank=True)
+
+    ## years: Empty string by default ''. If not empty it defines the years in
+    ##        which a stamp was stamped on a coin.
     years           = TextField('Im Einsatz in den Jahren ("" entspricht allen Jahren)', default='', blank=True)
 
+    ## comment: Any comment concerning a *Stamp*
     comment         = TextField('Kommentar', default='', blank=True)
 
-    country         = ForeignKey('Country', on_delete=CASCADE, null=True, blank=True)
-
 
     def __str__(self):
         return f"{self.name_short}"
@@ -73,40 +92,78 @@ class Stamp(Model):
 
 
 class Coin(Model):
+
+    # MANDATORY FIELDS which can only be set for the first time and cannot be modified:
+
+    ## id: Set automatically, only used by django
     id              = BigAutoField(primary_key=True)
 
+    ## value: Defines a coins value in Eurocents.
+    ## Possible values: [1, 2, 5, 10, 20, 50, 100, 200, 201, 202, 203]
+    ## Note: The values 201, 202, 203 represent special stamps of 2 Euro coins.
+    ##       So far there exist max. 3 different special stamps per year and *Country*
     value           = PositiveSmallIntegerField('Wert', default=100)
 
+    ## year: Defines the year when the coin was stamped
+    ## Possible values: [1999, YYYY]
     year            = PositiveSmallIntegerField('Jahr', default=year_now)
 
+    ## country: References a *Country* to which the coin belongs to
+    ## Possible values: ANY pre-defined *Country*
     country         = ForeignKey('Country', on_delete=CASCADE)
 
+    ## stamp: References a *Stamp* to which the coin belongs
+    ## Possible values: EITHER "Null" which means the default stamp of a *Country*
+    ##                  OR a pre-defined *Stamp*
     stamp           = ForeignKey('Stamp', on_delete=CASCADE, null=True, blank=True)
 
+
+    # OPTIONAL FIELDS which CAN be modified by a *User*:
+
+    ## name: The name of a 2 Euro special coin, i.e. "Michaeliskirche Hamburg"
     name            = TextField('Name', default='', blank=True)
 
+    ## found_by: References the *User* who found the coin, if the coin was found.
+    ## Possible values: EITHER "Null" which means nobody found the coin yet
+    ##                  OR a pre-defined *User*
     found_by        = ForeignKey('User', on_delete=CASCADE, null=True, blank=True)
 
+    ## found_on: The actual date someone found a coin
+    ## Note: This can be the same date a coin gets added to the database
+    ##       however this can also be a date prior to that moment (see date_added below)
     found_on        = DateField('Eingetragen am', default=date.today)
 
-    date_added      = DateTimeField('Hinzugefügt', auto_now_add=True)
+    ## circulation: The number of coins that have been stamped
-
-    date_modified   = DateTimeField('Geändert', auto_now=True)
-
     circulation     = PositiveIntegerField('Auflage', default=0)
 
+    ## buy_only: Wheter or not the coin can only be bought or is in free circulation
     buy_only        = BooleanField('Kursmünze', default=False)
 
+    ## checked: Wheter of not the coin got checked and sorted into the
+    ##          coincollector by the collection master
     checked         = BooleanField('Von Gigo geprüft und einsortiert', default=False)
 
+    ## in_collector: Wheter or not the coin is sorted into the special collector
     in_collector    = BooleanField('Im Eurocollector 2002', default=False)
 
+    ## exists: Wheter or not the coin actually exists
     exists          = BooleanField('Existiert', default=True)
 
+    ## fault_stamp: Wheter or not the coin is a fault stamp
     fault_stamp     = BooleanField('Fehlprägung', default=False)
 
+    ## comment: Any comment concerning a coin
     comment         = TextField('Kommentar', default='', blank=True)
 
 
+    # OPTIONAL FIELDS which CANNOT be modified by the *User*:
+
+    ## date_added: The date a found coin is added to the database
+    date_added      = DateTimeField('Hinzugefügt', auto_now_add=True)
+
+    ## date_modified: The datetime a previously added coin was modified
+    date_modified   = DateTimeField('Geändert', auto_now=True)
+
+
     def __str__(self):
         return f"{self.value} {self.stamp} aus {self.country.name} {self.year} {self.name}"