Better docstrings

dashboard/management/commands/import_observations.py

@@ -250,7 +250,8 @@ def batch_insert_observations(self, observations_to_insert: list[Observation]):
         for obs in inserted_observations:
             replaced = obs.migrate_linked_entities()
             if not replaced:
-                # That's a new observation in the system, it should be marked as unseen for every user
+                # That's a new observation in the system, it should be marked as unseen
+                # for every user (if older than delay + matching an alert)
                 obs.mark_as_unseen_for_all_users_if_needed()
 
     def add_arguments(self, parser: CommandParser) -> None:

dashboard/models.py

@@ -397,7 +397,14 @@ def date_older_than_user_delay(user: WebsiteUser, the_date) -> bool:
         )
 
     def mark_as_unseen_for_all_users_if_needed(self) -> None:
-        """Mark the observation as unseen for all users"""
+        """Mark the observation as unseen for all users if:
+        - it's more recent than the user's notification delay
+        - it matches at least one alert of the user
+
+        !! It doesn't look into the status (to check if the user has already seen
+        it), so it is only suitable for new observations, not replaced ones !!
+
+        """
 
         # TODO: test this logic !!
         for user in get_user_model().objects.all():