Add a lot of comments

apps/participation/models.py

@@ -17,6 +17,10 @@ from nio import RoomPreset, RoomVisibility
 
 
 class Team(models.Model):
+    """
+    The Team model represents a real team that participates to the Correspondances.
+    This only includes the registration detail.
+    """
     name = models.CharField(
         max_length=255,
         verbose_name=_("name"),
@@ -45,9 +49,15 @@ class Team(models.Model):
 
     @property
     def email(self):
+        """
+        :return: The mailing list to contact the team members.
+        """
         return f"equipe-{self.trigram.lower()}@{os.getenv('SYMPA_HOST', 'localhost')}"
 
     def create_mailing_list(self):
+        """
+        Create a new Sympa mailing list to contact the team.
+        """
         get_sympa_client().create_list(
             f"equipe-{self.trigram.lower()}",
             f"Équipe {self.name} ({self.trigram})",
@@ -58,10 +68,15 @@ class Team(models.Model):
         )
 
     def delete_mailing_list(self):
+        """
+        Drop the Sympa mailing list, if the team is empty or if the trigram changed.
+        """
         get_sympa_client().delete_list(f"equipe-{self.trigram}")
 
     def save(self, *args, **kwargs):
         if not self.access_code:
+            # if the team got created, generate the access code, create the contact mailing list
+            # and create a dedicated Matrix room.
             self.access_code = get_random_string(6)
             self.create_mailing_list()
 
@@ -90,6 +105,10 @@ class Team(models.Model):
 
 
 class Participation(models.Model):
+    """
+    The Participation model contains all data that are related to the participation:
+    chosen problem, validity status, videos,...
+    """
     team = models.OneToOneField(
         Team,
         on_delete=models.CASCADE,
@@ -149,6 +168,9 @@ class Participation(models.Model):
 
 
 class Video(models.Model):
+    """
+    The Video model only contains a link and a validity status.
+    """
     link = models.URLField(
         verbose_name=_("link"),
         help_text=_("The full video link."),
@@ -163,23 +185,38 @@ class Video(models.Model):
 
     @property
     def participation(self):
+        """
+        Retrives the participation that is associated to this video,
+        whatever it is a solution or a synthesis.
+        """
         try:
+            # If this is a solution
             return self.participation_solution
         except ObjectDoesNotExist:
+            # If this is a synthesis
             return self.participation_synthesis
 
     @property
     def platform(self):
+        """
+        According to the link, retrieve the platform that is used to upload the video.
+        """
         if "youtube.com" in self.link or "youtu.be" in self.link:
             return "youtube"
         return "unknown"
 
     @property
     def youtube_code(self):
+        """
+        If the video is uploaded on Youtube, search in the URL the video code.
+        """
         return re.compile("(https?://|)(www\\.|)(youtube\\.com/watch\\?v=|youtu\\.be/)([a-zA-Z0-9-_]*)?.*?")\
             .match("https://www.youtube.com/watch?v=73nsrixx7eI").group(4)
 
     def as_iframe(self):
+        """
+        Generate the HTML code to embed the video in an iframe, according to the type of the host platform.
+        """
         if self.platform == "youtube":
             return render_to_string("participation/youtube_iframe.html", context=dict(youtube_code=self.youtube_code))
         return None
@@ -194,6 +231,9 @@ class Video(models.Model):
 
 
 class Phase(models.Model):
+    """
+    The Phase model corresponds to the dates of the phase.
+    """
     phase_number = models.AutoField(
         primary_key=True,
         unique=True,
@@ -217,6 +257,9 @@ class Phase(models.Model):
 
     @classmethod
     def current_phase(cls):
+        """
+        Retrieve the current phase of this day
+        """
         qs = Phase.objects.filter(start__lte=timezone.now(), end__gte=timezone.now())
         if qs.exists():
             return qs.get()