From e52705edc3f283900f3d5d6440a84dd72ce82e87 Mon Sep 17 00:00:00 2001
From: Laouen Fernet <laouen.fernet@supelec.fr>
Date: Tue, 28 Apr 2020 12:19:05 +0200
Subject: [PATCH] Add some docstrings in multi_op/

---
 multi_op/forms.py              |  2 +-
 multi_op/preferences/forms.py  |  2 +-
 multi_op/preferences/models.py |  5 +++--
 multi_op/views.py              | 37 +++++++++++++++++++++++++++++-----
 4 files changed, 37 insertions(+), 9 deletions(-)

diff --git a/multi_op/forms.py b/multi_op/forms.py
index 297c03c8..08bc9123 100644
--- a/multi_op/forms.py
+++ b/multi_op/forms.py
@@ -36,7 +36,7 @@ from topologie.models import Dormitory
 
 
 class DormitoryForm(FormRevMixin, Form):
-    """Select a dorm"""
+    """Form used to select dormitories."""
 
     dormitory = forms.ModelMultipleChoiceField(
         queryset=Dormitory.objects.all(),
diff --git a/multi_op/preferences/forms.py b/multi_op/preferences/forms.py
index b6958546..a58410c7 100644
--- a/multi_op/preferences/forms.py
+++ b/multi_op/preferences/forms.py
@@ -34,7 +34,7 @@ from .models import Preferences
 
 
 class EditPreferencesForm(ModelForm):
-    """ Edit the ticket's settings"""
+    """Form used to edit the settings of multi_op."""
 
     class Meta:
         model = Preferences
diff --git a/multi_op/preferences/models.py b/multi_op/preferences/models.py
index c342bf41..8a185188 100644
--- a/multi_op/preferences/models.py
+++ b/multi_op/preferences/models.py
@@ -19,7 +19,8 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 """
-Fichier définissant les administration des models de preference 
+multi_op preferences model. The settings are used when managing dormitories
+with multiple operators.
 """
 
 
@@ -28,7 +29,7 @@ from django.utils.translation import ugettext_lazy as _
 
 
 class Preferences(models.Model):
-    """ Definition of the app settings"""
+    """Definition of the settings of multi_op."""
 
     enabled_dorm = models.ManyToManyField(
         "topologie.Dormitory",
diff --git a/multi_op/views.py b/multi_op/views.py
index 266c8a15..729eae27 100644
--- a/multi_op/views.py
+++ b/multi_op/views.py
@@ -53,7 +53,13 @@ from .preferences.forms import EditPreferencesForm
 
 
 def display_rooms_connection(request, dormitory=None):
-    """View to display global state of connection state"""
+    """View used to display an overview of the rooms' connection state.
+
+    Args:
+        request: django request.
+        dormitory: Dormitory, the dormitory used to filter rooms. If no
+            dormitory is given, all rooms are displayed (default: None).
+    """
     room_list = Room.objects.select_related("building__dormitory").order_by(
         "building_dormitory", "port"
     )
@@ -81,19 +87,30 @@ def display_rooms_connection(request, dormitory=None):
 @login_required
 @can_view_all(Room)
 def aff_state_global(request):
+    """View used to display the connection state of all rooms."""
     return display_rooms_connection(request)
 
 
 @login_required
 @can_view(Dormitory)
 def aff_state_dormitory(request, dormitory, dormitoryid):
+    """View used to display the connection state of the rooms in the given
+    dormitory.
+
+    Args:
+        request: django request.
+        dormitory: Dormitory, the dormitory used to filter rooms.
+        dormitoryid: int, the id of the dormitory.
+    """
     return display_rooms_connection(dormitory=dormitory)
 
 
 @login_required
 @can_view_all(Room)
 def aff_pending_connection(request):
-    """Aff pending Rooms to connect on our network"""
+    """View used to display rooms pending connection to the organisation's
+    network.
+    """
     room_list = (
         Room.objects.select_related("building__dormitory")
         .filter(port__isnull=True)
@@ -128,7 +145,9 @@ def aff_pending_connection(request):
 @login_required
 @can_view_all(Room)
 def aff_pending_disconnection(request):
-    """Aff pending Rooms to disconnect from our network"""
+    """View used to display rooms pending disconnection from the organisation's
+    network.
+    """
     room_list = (
         Room.objects.select_related("building__dormitory")
         .filter(port__isnull=False)
@@ -163,7 +182,13 @@ def aff_pending_disconnection(request):
 @login_required
 @can_edit(Room)
 def disconnect_room(request, room, roomid):
-    """Action of disconnecting a room"""
+    """View used to disconnect a room.
+
+    Args:
+        request: django request.
+        room: Room, the room to be disconnected.
+        roomid: int, the id of the room.
+    """
     room.port_set.clear()
     room.save()
     messages.success(request, _("The room %s was disconnected.") % room)
@@ -171,5 +196,7 @@ def disconnect_room(request, room, roomid):
 
 
 def navbar_user():
-    """View to display the app in user's dropdown in the navbar"""
+    """View used to display a link to manage operators in the navbar (in the
+    dropdown menu Topology).
+    """
     return ("topologie", render_to_string("multi_op/navbar.html"))