Add some more documentation in events.models

events/models.py

@@ -1,3 +1,33 @@
+"""
+Event framework for GestioCOF and GestioBDS.
+
+The events implemented in this module provide two type of customisation to event
+creators (the COF and BDS staff): options and extra (text) field.
+
+Options
+-------
+
+An option is an extra field in the registration form with a predefined list of available
+choices. Any number of options can be added to an event.
+
+For instance, a typical use-case if for events where meals are served to participants
+with different possible menus, say: vegeterian / vegan / without pork / etc. This
+example can be implemented with an `Option(name="menu")` and an `OptionChoice` for each
+available menu.
+
+In this example, the choice was exclusive: participants can only chose one menu. For
+situations, where multiple choices can be made at the same time, use the `multi_choices`
+flag.
+
+Extra fields
+------------
+
+Extra fields can also be added to the registration form that can receive arbitrary text.
+Typically, this can be a "remark" field (prefer the LONGTEXT option in this case) or
+small form entries such as "phone number" or "emergency contact" (prefer the SHORTTEXT
+option in this case).
+"""
+
 from django.contrib.auth import get_user_model
 from django.db import models
 from django.utils.translation import gettext_lazy as _
@@ -29,12 +59,11 @@ class Event(models.Model):
 
 
 class Option(models.Model):
-    """Event options to be selected by participants at registration.
+    """Extra form fields with a limited set of available choices.
 
-    The possible choices are instances of `OptionChoice` (see below). A typical example
+    The available choices are given by `OptionChoice`s (see below). A typical use-case
-    is when the participants have the choice between different meal types (e.g. vegan /
+    is for events where the participants have the choice between different menus (e.g.
-    vegetarian / no pork / with meat). In this case, the "meal type" is an `Option` and
+    vegan / vegetarian / without-pork / whatever).
-    the three alternatives are `OptionChoice`s.
     """
 
     event = models.ForeignKey(Event, on_delete=models.CASCADE, related_name="options")
@@ -50,7 +79,7 @@ class Option(models.Model):
 
 
 class OptionChoice(models.Model):
-    """A possible choice for an event option (see Option)."""
+    """A possible choice for an event option."""
 
     option = models.ForeignKey(Option, on_delete=models.CASCADE, related_name="choices")
     choice = models.CharField(_("choix"), max_length=200)
@@ -64,11 +93,11 @@ class OptionChoice(models.Model):
 
 
 class ExtraField(models.Model):
-    """Extra event field, for event creators.
+    """Extra event field receiving arbitrary text.
 
     Extra text field that can be added by event creators to the event registration form.
-    Typical examples are "remarks" fields (of type LONGTEXT) or more specific questions
+    Typical examples are "remarks" fields (of type LONGTEXT) or more specific fields
-    such as "emergency contact".
+    such as "emergency contact" (of type SHORTTEXT probably?).
     """
 
     LONGTEXT = "longtext"
@@ -87,6 +116,8 @@ class ExtraField(models.Model):
 
 
 class ExtraFieldContent(models.Model):
+    """Value entered in an extra field."""
+
     field = models.ForeignKey(ExtraField, on_delete=models.CASCADE)
     registration = models.ForeignKey(
         "Registration", on_delete=models.CASCADE, related_name="extra_info"
@@ -106,6 +137,8 @@ class ExtraFieldContent(models.Model):
 
 
 class Registration(models.Model):
+    """A user registration to an event."""
+
     event = models.ForeignKey(Event, on_delete=models.CASCADE)
     user = models.ForeignKey(User, on_delete=models.CASCADE)
     options_choices = models.ManyToManyField(OptionChoice)