From 5a7d779a907efa9153389f9c84593c392e557fa1 Mon Sep 17 00:00:00 2001 From: Pierre-antoine Comby Date: Tue, 21 Jan 2020 22:06:06 +0100 Subject: [PATCH] Add/ Complete docstring for every models. --- apps/activity/models.py | 14 +++++++++++--- apps/member/models.py | 12 +++++++++--- apps/note/models/notes.py | 23 +++++++++++++++++------ apps/note/models/transactions.py | 19 +++++++++++++++++++ 4 files changed, 56 insertions(+), 12 deletions(-) diff --git a/apps/activity/models.py b/apps/activity/models.py index 50a8d781..52f4e0b6 100644 --- a/apps/activity/models.py +++ b/apps/activity/models.py @@ -9,7 +9,12 @@ from django.utils.translation import gettext_lazy as _ class ActivityType(models.Model): """ - Type of Activity, (e.g "Pot", "Soirée Club") and associated properties + Type of Activity, (e.g "Pot", "Soirée Club") and associated properties. + + Activity Type are used as a search field for Activity, and determine how + some rules about the activity: + - Can people be invited + - What is the entrance fee. """ name = models.CharField( verbose_name=_('name'), @@ -32,7 +37,9 @@ class ActivityType(models.Model): class Activity(models.Model): """ - An IRL event organized by a club for others. + An IRL event organized by a club for other club. + + By default the invited clubs should be the Club containing all the active accounts. """ name = models.CharField( verbose_name=_('name'), @@ -73,7 +80,7 @@ class Activity(models.Model): class Guest(models.Model): """ - People who are not current members of any clubs, and invited by someone who is a current member. + People who are not current members of any clubs, and are invited by someone who is a current member. """ activity = models.ForeignKey( Activity, @@ -92,6 +99,7 @@ class Guest(models.Model): null=True, ) entry_transaction = models.ForeignKey( + null=True, 'note.Transaction', on_delete=models.PROTECT, ) diff --git a/apps/member/models.py b/apps/member/models.py index 10a51395..883f9b49 100644 --- a/apps/member/models.py +++ b/apps/member/models.py @@ -13,8 +13,9 @@ class Profile(models.Model): """ An user profile - We do not want to patch the Django Contrib Auth User class + We do not want to patch the Django Contrib :model:`auth.User`model; so this model add an user profile with additional information. + """ user = models.OneToOneField( settings.AUTH_USER_MODEL, @@ -53,7 +54,8 @@ class Profile(models.Model): class Club(models.Model): """ - A student club + A club is a group of people, whose membership is handle by their + :model:`member.Membership`, and gives access to right defined by a :model:`member.Role`. """ name = models.CharField( verbose_name=_('name'), @@ -101,7 +103,10 @@ class Club(models.Model): class Role(models.Model): """ - Role that an user can have in a club + Role that an :model:`auth.User` can have in a :model:`member.Club` + + TODO: Integrate the right management, and create some standard Roles at the + creation of the club. """ name = models.CharField( verbose_name=_('name'), @@ -117,6 +122,7 @@ class Role(models.Model): class Membership(models.Model): """ Register the membership of a user to a club, including roles and membership duration. + """ user = models.ForeignKey( settings.AUTH_USER_MODEL, diff --git a/apps/note/models/notes.py b/apps/note/models/notes.py index debd6b88..e3ab7931 100644 --- a/apps/note/models/notes.py +++ b/apps/note/models/notes.py @@ -18,7 +18,11 @@ Defines each note types class Note(PolymorphicModel): """ - An model, use to add transactions capabilities + Gives transactions capabilities. Note is a Polymorphic Model, use as based + for the models :model:`note.NoteUser` and :model:`note.NoteClub`. + A Note principaly store the actual balance of someone/some club. + A Note can be searched find throught an :model:`note.Alias` + """ balance = models.IntegerField( verbose_name=_('account balance'), @@ -94,7 +98,7 @@ class Note(PolymorphicModel): class NoteUser(Note): """ - A Note associated to an User + A :model:`note.Note` associated to an unique :model:`auth.User`. """ user = models.OneToOneField( settings.AUTH_USER_MODEL, @@ -116,7 +120,7 @@ class NoteUser(Note): class NoteClub(Note): """ - A Note associated to a Club + A :model:`note.Note` associated to an unique :model:`member.Club` """ club = models.OneToOneField( 'member.Club', @@ -133,17 +137,18 @@ class NoteClub(Note): return str(self.club) def pretty(self): - return _("Note for %(club)s club") % {'club': str(self.club)} + return _("Note of %(club)s club") % {'club': str(self.club)} class NoteSpecial(Note): """ - A Note for special account, where real money enter or leave the system + A :model:`note.Note` for special accounts, where real money enter or leave the system - bank check - credit card - bank transfer - cash - refund + This Type of Note is not associated to a :model:`auth.User` or :model:`member.Club` . """ special_type = models.CharField( verbose_name=_('type'), @@ -161,7 +166,13 @@ class NoteSpecial(Note): class Alias(models.Model): """ - An alias labels a Note instance, only for user and clubs + points toward a :model:`note.NoteUser` or :model;`note.NoteClub` instance. + Alias are unique, but a :model:`note.NoteUser` or :model:`note.NoteClub` can + have multiples aliases. + + Aliases name are also normalized, two differents :model:`note.Note` can not + have the same normalized alias, to avoid confusion when referring orally to + it. """ name = models.CharField( verbose_name=_('name'), diff --git a/apps/note/models/transactions.py b/apps/note/models/transactions.py index 42eff212..4ce23311 100644 --- a/apps/note/models/transactions.py +++ b/apps/note/models/transactions.py @@ -15,6 +15,11 @@ Defines transactions class TransactionTemplate(models.Model): + """ + Defined a reccurent transaction + + associated to selling something (a burger, a beer, ...) + """ name = models.CharField( verbose_name=_('name'), max_length=255, @@ -44,6 +49,15 @@ class TransactionTemplate(models.Model): class Transaction(models.Model): + """ + General transaction between two :model:`note.Note` + + amount is store in centimes of currency, making it a positive integer + value. (from someone to someone else) + + TODO: Ensure source != destination. + """ + source = models.ForeignKey( Note, on_delete=models.PROTECT, @@ -112,6 +126,11 @@ class Transaction(models.Model): class MembershipTransaction(Transaction): + """ + Special type of :model:`note.Transaction` associated to a :model:`member.Membership`. + + """ + membership = models.OneToOneField( 'member.Membership', on_delete=models.PROTECT,