Add some docstrings in tickets/

tickets/forms.py

@@ -35,7 +35,7 @@ from .models import Ticket, CommentTicket
 
 
 class NewTicketForm(FormRevMixin, ModelForm):
-    """ Creation of a ticket"""
+    """Form used to create tickets."""
 
     class Meta:
         model = Ticket
@@ -53,7 +53,7 @@ class NewTicketForm(FormRevMixin, ModelForm):
 
 
 class EditTicketForm(FormRevMixin, ModelForm):
-    """ Creation of a ticket"""
+    """Form used to edit tickets."""
 
     class Meta:
         model = Ticket
@@ -65,7 +65,7 @@ class EditTicketForm(FormRevMixin, ModelForm):
 
 
 class CommentTicketForm(FormRevMixin, ModelForm):
-    """Edit and create comment to a ticket"""
+    """Form used to create and edit comments of a ticket."""
 
     class Meta:
         model = CommentTicket

tickets/models.py

@@ -46,7 +46,23 @@ from .preferences.models import TicketOption
 
 
 class Ticket(AclMixin, models.Model):
-    """Model of a ticket"""
+    """Model of a ticket.
+
+    Attributes:
+        user: User, the user creating the ticket.
+        title: the title of the ticket, chosen by the user.
+        description: the main content of the ticket, written by the user to
+            explain their problem.
+        date: datetime, the date of creation of the ticket.
+        email: the email address used to reply to the ticket.
+        solved: boolean, True if the problem explained in the ticket has been
+            solved, False otherwise. It is used to see easily which tickets
+            still require attention.
+        language: the language of the ticket, used to select the appropriate
+            template when sending automatic emails, e.g. ticket creation.
+        request: the request displayed if there is an error when sending emails
+            related to the ticket.
+    """
 
     user = models.ForeignKey(
         "users.User",
@@ -86,7 +102,7 @@ class Ticket(AclMixin, models.Model):
 
     @cached_property
     def opened_by(self):
-        """Return full name of this ticket opener"""
+        """Get the full name of the user who opened the ticket."""
         if self.user:
             return self.user.get_full_name()
         else:
@@ -94,10 +110,13 @@ class Ticket(AclMixin, models.Model):
 
     @cached_property
     def get_mail(self):
-        """Return the mail of the owner of this ticket"""
+        """Get the email address of the user who opened the ticket."""
         return self.email or self.user.get_mail 
 
     def publish_mail(self):
+        """Send an email for a newly opened ticket to the address set in the
+        preferences.
+        """
         site_url = GeneralOption.get_cached_value("main_site_url")
         to_addr = TicketOption.get_cached_value("publish_address")
         context = {"ticket": self, "site_url": site_url}
@@ -120,8 +139,8 @@ class Ticket(AclMixin, models.Model):
 
 
     def can_view(self, user_request, *_args, **_kwargs):
-        """ Check that the user has the right to view the ticket
-        or that it is the author"""
+        """Check that the user has the right to view the ticket
+        or that it is the author."""
         if (
             not user_request.has_perm("tickets.view_ticket")
             and self.user != user_request
@@ -136,7 +155,7 @@ class Ticket(AclMixin, models.Model):
 
     @staticmethod
     def can_view_all(user_request, *_args, **_kwargs):
-        """ Check that the user has access to the list of all tickets"""
+        """Check that the user has access to the list of all tickets."""
         can = user_request.has_perm("tickets.view_ticket")
         return (
             can,
@@ -147,12 +166,23 @@ class Ticket(AclMixin, models.Model):
         )
 
     def can_create(user_request, *_args, **_kwargs):
-        """ Authorise all users to open tickets """
+        """Authorise all users to open tickets."""
         return True, None, None
 
 
 class CommentTicket(AclMixin, models.Model):
-    """A comment of a ticket"""
+    """A comment of a ticket.
+
+    Attributes:
+        date: datetime, the date of creation of the comment.
+        comment: the text written as a comment to a ticket.
+        parent_ticket: the ticket which is commented.
+        created_at: datetime, the date of creation of the comment.
+        created_by: the user who wrote the comment.
+        request: the request used if there is an error when sending emails
+            related to the comment.
+    """
+
     date = models.DateTimeField(auto_now_add=True)
     comment = models.TextField(
         max_length=4095,
@@ -180,8 +210,8 @@ class CommentTicket(AclMixin, models.Model):
         return CommentTicket.objects.filter(parent_ticket=self.parent_ticket, pk__lt=self.pk).count() + 1
 
     def can_view(self, user_request, *_args, **_kwargs):
-        """ Check that the user has the right to view the ticket comment
-        or that it is the author"""
+        """Check that the user has the right to view the ticket comment
+        or that it is the author."""
         if (
             not user_request.has_perm("tickets.view_commentticket")
             and self.parent_ticket.user != user_request
@@ -195,8 +225,8 @@ class CommentTicket(AclMixin, models.Model):
             return True, None, None
 
     def can_edit(self, user_request, *_args, **_kwargs):
-        """ Check that the user has the right to edit the ticket comment
-        or that it is the author"""
+        """Check that the user has the right to edit the ticket comment
+        or that it is the author."""
         if (
             not user_request.has_perm("tickets.change_commentticket")
             and (self.parent_ticket.user != user_request or self.parent_ticket.user != self.created_by)
@@ -211,7 +241,7 @@ class CommentTicket(AclMixin, models.Model):
 
     @staticmethod
     def can_view_all(user_request, *_args, **_kwargs):
-        """ Check that the user has access to the list of all tickets comments"""
+        """Check that the user has access to the list of all tickets comments."""
         can = user_request.has_perm("tickets.view_commentticket")
         return (
             can,
@@ -225,7 +255,9 @@ class CommentTicket(AclMixin, models.Model):
         return "Comment " + str(self.comment_id) + " on " + str(self.parent_ticket)
 
     def publish_mail(self):
-        """Send mail to user and admin after new comment"""
+        """Send an email for a newly written comment to the ticket's author and
+        to the address set in the preferences.
+        """
         site_url = GeneralOption.get_cached_value("main_site_url")
         to_addr = TicketOption.get_cached_value("publish_address")
         context = {"comment": self, "site_url": site_url}
@@ -246,7 +278,7 @@ class CommentTicket(AclMixin, models.Model):
 
 @receiver(post_save, sender=Ticket)
 def ticket_post_save(**kwargs):
-    """ Send the mail to publish the new ticket """
+    """Call the method to publish an email when a ticket is created."""
     if kwargs["created"]:
         if TicketOption.get_cached_value("publish_address"):
             ticket = kwargs["instance"]
@@ -255,7 +287,7 @@ def ticket_post_save(**kwargs):
 
 @receiver(post_save, sender=CommentTicket)
 def comment_post_save(**kwargs):
-    """ Send the mail to publish the new comment """
+    """Call the method to publish an email when a comment is created."""
     if kwargs["created"]:
         if TicketOption.get_cached_value("publish_address"):
             comment = kwargs["instance"]

tickets/preferences/forms.py

@@ -32,7 +32,7 @@ from .models import TicketOption
 
 
 class EditTicketOptionForm(FormRevMixin, ModelForm):
-    """ Edit the ticket's settings"""
+    """Form used to edit the settings of tickets."""
 
     class Meta:
         model = TicketOption

tickets/preferences/models.py

@@ -32,7 +32,7 @@ from preferences.models import PreferencesModel
 
 
 class TicketOption(AclMixin, PreferencesModel):
-    """ Definition of the ticket's settings"""
+    """Definition of the settings of tickets."""
 
     publish_address = models.EmailField(
         help_text=_(

tickets/preferences/views.py

@@ -42,7 +42,7 @@ from . import models
 
 
 def aff_preferences(request):
-    """ View to display the settings of the tickets in the preferences page"""
+    """View used to display the settings of tickets in the preferences page."""
     pref, created = models.TicketOption.objects.get_or_create()
     context = {
         "preferences": pref,

tickets/views.py

@@ -52,7 +52,7 @@ from .forms import NewTicketForm, EditTicketForm, CommentTicketForm
 
 
 def new_ticket(request):
-    """ Ticket creation view"""
+    """View used to display the creation form of tickets."""
     ticketform = NewTicketForm(request.POST or None, request=request)
     if ticketform.is_valid():
         ticketform.save()
@@ -76,7 +76,7 @@ def new_ticket(request):
 @login_required
 @can_view(Ticket)
 def aff_ticket(request, ticket, ticketid):
-    """View to display only one ticket"""
+    """View used to display a single ticket."""
     comments = CommentTicket.objects.filter(parent_ticket=ticket)
     return render(
         request,
@@ -88,7 +88,7 @@ def aff_ticket(request, ticket, ticketid):
 @login_required
 @can_edit(Ticket)
 def change_ticket_status(request, ticket, ticketid):
-    """View to edit ticket state"""
+    """View used to change a ticket's status."""
     ticket.solved = not ticket.solved
     ticket.save()
     return redirect(
@@ -99,7 +99,7 @@ def change_ticket_status(request, ticket, ticketid):
 @login_required
 @can_edit(Ticket)
 def edit_ticket(request, ticket, ticketid):
-    """ Ticket creation view"""
+    """View used to display the edit form of tickets."""
     ticketform = EditTicketForm(request.POST or None, instance=ticket)
     if ticketform.is_valid():
         ticketform.save()
@@ -120,7 +120,7 @@ def edit_ticket(request, ticket, ticketid):
 @login_required
 @can_view(Ticket)
 def add_comment(request, ticket, ticketid):
-    """ Add a comment to a ticket"""
+    """View used to add a comment to a ticket."""
     commentticket = CommentTicketForm(request.POST or None, request=request)
     if commentticket.is_valid():
         commentticket = commentticket.save(commit=False)
@@ -139,7 +139,7 @@ def add_comment(request, ticket, ticketid):
 @login_required
 @can_edit(CommentTicket)
 def edit_comment(request, commentticket_instance, **_kwargs):
-    """ Edit a comment of a ticket"""
+    """View used to edit a comment of a ticket."""
     commentticket = CommentTicketForm(request.POST or None, instance=commentticket_instance)
     if commentticket.is_valid():
         ticketid = commentticket_instance.parent_ticket.id
@@ -157,7 +157,7 @@ def edit_comment(request, commentticket_instance, **_kwargs):
 @login_required
 @can_delete(CommentTicket)
 def del_comment(request, commentticket, **_kwargs):
-    """Delete a comment of a ticket"""
+    """View used to delete a comment of a ticket."""
     if request.method == "POST":
         ticketid = commentticket.parent_ticket.id
         commentticket.delete()
@@ -173,7 +173,7 @@ def del_comment(request, commentticket, **_kwargs):
 @login_required
 @can_view_all(Ticket)
 def aff_tickets(request):
-    """ View to display all the tickets """
+    """View used to display all tickets."""
     tickets_list = Ticket.objects.all().order_by("-date")
     nbr_tickets = tickets_list.count()
     nbr_tickets_unsolved = tickets_list.filter(solved=False).count()
@@ -198,7 +198,7 @@ def aff_tickets(request):
 
 # views cannoniques des apps optionnels
 def profil(request, user):
-    """ View to display the ticket's module on the profil"""
+    """View used to display the tickets on a user's profile."""
     tickets_list = Ticket.objects.filter(user=user).all().order_by("-date")
     nbr_tickets = tickets_list.count()
     nbr_tickets_unsolved = tickets_list.filter(solved=False).count()
@@ -223,16 +223,19 @@ def profil(request, user):
 
 
 def contact(request):
-    """View to display a contact address on the contact page
-    used here to display a link to open a ticket"""
+    """View used to display contact addresses to be used for tickets on the
+    contact page.
+    """
     return render_to_string("tickets/contact.html")
 
 
 def navbar_user():
-    """View to display the ticket link in thet user's dropdown in the navbar"""
+    """View used to display a link to tickets in the navbar (in the dropdown
+    menu Users).
+    """
     return ("users", render_to_string("tickets/navbar.html"))
 
 
 def navbar_logout():
-    """View to display the ticket link to log out users"""
+    """View used to display a link to open tickets for logged out users."""
     return render_to_string("tickets/navbar_logout.html")