From a39c5fe66a339f286d3d5b4b4a2cca9ba85b2ec7 Mon Sep 17 00:00:00 2001
From: Andrew Tavis McAllister <andrew.t.mcallister@gmail.com>
Date: Sat, 4 May 2024 14:24:52 +0200
Subject: [PATCH] Misc docstring and comment changes

---
 backend/authentication/admin.py           | 15 ++++++++++-----
 backend/authentication/models.py          | 12 +-----------
 backend/authentication/serializers.py     |  4 ++++
 backend/authentication/tests.py           |  4 ++++
 backend/backend/mixins/models.py          | 13 ++++++++-----
 backend/backend/settings.py               |  4 ++--
 backend/content/models.py                 | 18 +-----------------
 backend/content/serializers.py            |  4 ++++
 backend/content/tests.py                  |  4 ++++
 backend/content/views.py                  |  7 ++++---
 backend/entities/models.py                | 20 +-------------------
 backend/entities/serializers.py           |  4 ++++
 backend/entities/tests.py                 |  4 ++++
 backend/events/models.py                  | 17 +----------------
 backend/events/serializers.py             |  4 ++++
 backend/events/tests.py                   |  4 ++++
 backend/manage.py                         |  8 ++++++--
 backend/tests/throttle.py                 |  1 -
 frontend/playwright.config.ts             | 14 +++++++-------
 frontend/tests/specs/landing-page.spec.ts |  4 ++--
 20 files changed, 75 insertions(+), 90 deletions(-)

diff --git a/backend/authentication/admin.py b/backend/authentication/admin.py
index f01a9e6f0..a157b8588 100644
--- a/backend/authentication/admin.py
+++ b/backend/authentication/admin.py
@@ -18,8 +18,11 @@
 
 
 class UserCreationForm(forms.ModelForm[UserModel]):
-    """A form for creating new users. Includes all the required
-    fields, plus a repeated password."""
+    """
+    A form for creating new users.
+
+    Includes all the required fields, plus a repeated password.
+    """
 
     password1 = forms.CharField(label="Password", widget=forms.PasswordInput)
     password2 = forms.CharField(
@@ -48,9 +51,11 @@ def save(self, commit: bool = True) -> UserModel:
 
 
 class UserChangeForm(forms.ModelForm[UserModel]):
-    """A form for updating users. Includes all the fields on
-    the user, but replaces the password field with admin's
-    disabled password hash display field.
+    """
+    A form for updating users.
+
+    Includes all the fields on the user.
+    Replaces the password field with admin's disabled password hash display field.
     """
 
     password = ReadOnlyPasswordHashField()
diff --git a/backend/authentication/models.py b/backend/authentication/models.py
index 72a51c036..0847d3f30 100644
--- a/backend/authentication/models.py
+++ b/backend/authentication/models.py
@@ -1,15 +1,5 @@
 """
-Authentication Models
-
-This file contains models for the authentication app.
-
-Contents:
-    - SupportEntityType
-    - Support
-    - UserModel
-    - UserResource
-    - UserTask
-    - UserTopic
+Models for the authentication app.
 """
 
 from typing import Any
diff --git a/backend/authentication/serializers.py b/backend/authentication/serializers.py
index 15009e35f..758621a6d 100644
--- a/backend/authentication/serializers.py
+++ b/backend/authentication/serializers.py
@@ -1,3 +1,7 @@
+"""
+Serializers for the authentication app.
+"""
+
 import re
 from typing import Any, Dict, Union
 
diff --git a/backend/authentication/tests.py b/backend/authentication/tests.py
index 563989fb6..8261e6aab 100644
--- a/backend/authentication/tests.py
+++ b/backend/authentication/tests.py
@@ -1,3 +1,7 @@
+"""
+Testing for the authentication app.
+"""
+
 import pytest
 from .factories import (
     SupportEntityTypeFactory,
diff --git a/backend/backend/mixins/models.py b/backend/backend/mixins/models.py
index 41c7a2eb4..deff6c1b7 100644
--- a/backend/backend/mixins/models.py
+++ b/backend/backend/mixins/models.py
@@ -6,11 +6,10 @@
 
 class IdMixin(models.Model):
     """
-    Mixin for models with incrementing Integer primary key
-    ------------------------------------------------------
+    Mixin for models with incrementing Integer primary key.
 
     This mixin is used for models that have an incrementing Integer primary key.
-    Default in django is an incrementing Integer primary key. Creating this explicity helps with code highlighting.
+    Default in Django is an incrementing Integer primary key. Creating this explicitly helps with code highlighting.
     """
 
     id = models.AutoField(primary_key=True)
@@ -20,7 +19,9 @@ class Meta:
 
 
 class UUIDModelMixin(models.Model):
-    """Mixin for models with UUID primary key"""
+    """
+    Mixin for models with UUID primary key.
+    """
 
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
 
@@ -29,7 +30,9 @@ class Meta:
 
 
 class CreationDeletionMixin(models.Model):
-    """Mixin for model with creation and deletion date"""
+    """
+    Mixin for model with creation and deletion date.
+    """
 
     creation_date = models.DateTimeField(_("Created at"), auto_now_add=True)
     deletion_date = models.DateTimeField(_("Deletion date"), null=True, blank=True)
diff --git a/backend/backend/settings.py b/backend/backend/settings.py
index cf2ef2f9b..036855a7f 100644
--- a/backend/backend/settings.py
+++ b/backend/backend/settings.py
@@ -1,10 +1,10 @@
 """
 Django settings for activist.org.
 
-For more information on this file, see
+For more information on this file, see:
 https://docs.djangoproject.com/en/4.1/topics/settings/
 
-For the full list of settings and their values, see
+For the full list of settings and their values, see:
 https://docs.djangoproject.com/en/4.1/ref/settings/
 """
 
diff --git a/backend/content/models.py b/backend/content/models.py
index 119745d45..55c7b4885 100644
--- a/backend/content/models.py
+++ b/backend/content/models.py
@@ -1,21 +1,5 @@
 """
-Content Models
-
-This file contains models for the content app.
-
-Contents:
-    - Discussion
-    - DiscussionEntry
-    - Faq
-    - Resource
-    - Task
-    - Topic
-    - Tag
-    - ResourceTopic
-    - ResourceTag
-    - TopicFormat
-    - DiscussionTag
-    - Image
+Models for the content app.
 """
 
 from uuid import uuid4
diff --git a/backend/content/serializers.py b/backend/content/serializers.py
index 0da6e0c7a..c3a0aa20b 100644
--- a/backend/content/serializers.py
+++ b/backend/content/serializers.py
@@ -1,3 +1,7 @@
+"""
+Serializers for the content app.
+"""
+
 from typing import Dict, Union
 
 from django.utils.translation import gettext as _
diff --git a/backend/content/tests.py b/backend/content/tests.py
index 4fd01c12e..42bcf741f 100644
--- a/backend/content/tests.py
+++ b/backend/content/tests.py
@@ -1,3 +1,7 @@
+"""
+Testing for the content app.
+"""
+
 from .factories import ResourceFactory, TaskFactory, TopicFactory, ResourceTopicFactory
 from tests.throttle import BaseTestThrottle
 from django.urls import reverse
diff --git a/backend/content/views.py b/backend/content/views.py
index 19134a25d..2ece0d467 100644
--- a/backend/content/views.py
+++ b/backend/content/views.py
@@ -74,7 +74,9 @@ def list(self, request: Request) -> Response:
         return self.get_paginated_response(self.paginate_queryset(serializer.data))
 
     def update(self, request: Request, pk: str | None = None) -> Response:
-        """Just the created_by user can update the discussion"""
+        """
+        Just the created_by user can update the discussion.
+        """
         item = self.get_object()
         if item.created_by != request.user:
             return Response(
@@ -100,8 +102,7 @@ def partial_update(self, request: Request, pk: str | None = None) -> Response:
 
     def destroy(self, request: Request, pk: str | None = None) -> Response:
         """
-        Deleted the whole discussion
-        - Only the created_by user can delete it
+        Deleted the whole discussion - requires created_by user.
         """
         item = self.get_object()
         if item.created_by != request.user:
diff --git a/backend/entities/models.py b/backend/entities/models.py
index fb68a61a2..5084555a7 100644
--- a/backend/entities/models.py
+++ b/backend/entities/models.py
@@ -1,23 +1,5 @@
 """
-Entities Models
-
-This file contains models for the entities app.
-
-Contents:
-    - Organization
-    - OrganizationApplication
-    - OrganizationEvent
-    - OrganizationImage
-    - OrganizationMember
-    - OrganizationResource
-    - Group
-    - OrganizationTask
-    - OrganizationTopic
-    - GroupEvent
-    - GroupImage
-    - GroupMember
-    - GroupResource
-    - GroupTopic
+Models for the entities app.
 """
 
 from uuid import uuid4
diff --git a/backend/entities/serializers.py b/backend/entities/serializers.py
index 13b393cd0..b49634165 100644
--- a/backend/entities/serializers.py
+++ b/backend/entities/serializers.py
@@ -1,3 +1,7 @@
+"""
+Serializers for the entities app.
+"""
+
 from rest_framework import serializers
 
 from .models import (
diff --git a/backend/entities/tests.py b/backend/entities/tests.py
index ea7c6ff11..29fcfc4bc 100644
--- a/backend/entities/tests.py
+++ b/backend/entities/tests.py
@@ -1,3 +1,7 @@
+"""
+Testing for the entities app.
+"""
+
 from django.urls import reverse
 from tests.throttle import BaseTestThrottle
 
diff --git a/backend/events/models.py b/backend/events/models.py
index 57f5aa0e9..a36e9f883 100644
--- a/backend/events/models.py
+++ b/backend/events/models.py
@@ -1,20 +1,5 @@
 """
-Events Models
-
-This file contains models for the events app.
-
-Contents:
-    - Event
-    - Format
-    - Role
-    - EventAttendee
-    - EventFormat
-    - EventAttendeeStatus
-    - EventResource
-    - EventRole
-    - EventTask
-    - EventTopic
-    - EventTag
+Models for the events app.
 """
 
 from uuid import uuid4
diff --git a/backend/events/serializers.py b/backend/events/serializers.py
index 08e7347c4..5668edcf1 100644
--- a/backend/events/serializers.py
+++ b/backend/events/serializers.py
@@ -1,3 +1,7 @@
+"""
+Serializers for the events app.
+"""
+
 from typing import Dict, Union
 
 from django.utils.dateparse import parse_datetime
diff --git a/backend/events/tests.py b/backend/events/tests.py
index 81c1cf861..9858bf657 100644
--- a/backend/events/tests.py
+++ b/backend/events/tests.py
@@ -1,3 +1,7 @@
+"""
+Testing for the events app.
+"""
+
 from django.urls import reverse
 from tests.throttle import BaseTestThrottle
 
diff --git a/backend/manage.py b/backend/manage.py
index 1a54aed75..1d59a7d10 100755
--- a/backend/manage.py
+++ b/backend/manage.py
@@ -1,12 +1,16 @@
 #!/usr/bin/env python
-"""Django's command-line utility for administrative tasks."""
+"""
+Django's command-line utility for administrative tasks.
+"""
 
 import os
 import sys
 
 
 def main() -> None:
-    """Run administrative tasks."""
+    """
+    Run administrative tasks.
+    """
     os.environ.setdefault("DJANGO_SETTINGS_MODULE", "backend.settings")
     try:
         from django.core.management import execute_from_command_line
diff --git a/backend/tests/throttle.py b/backend/tests/throttle.py
index 445abc5c0..874861bfd 100644
--- a/backend/tests/throttle.py
+++ b/backend/tests/throttle.py
@@ -10,7 +10,6 @@
 class BaseTestThrottle:
     """
     Base class for testing throttling.
-    ----------------------------------
 
     This is a base class for testing throttling.
 
diff --git a/frontend/playwright.config.ts b/frontend/playwright.config.ts
index 7e39a38d8..c20b3df90 100644
--- a/frontend/playwright.config.ts
+++ b/frontend/playwright.config.ts
@@ -16,31 +16,31 @@ const environments = {
   prod: "https://activist.org",
 };
 
-// Determine the environment from the command line or default to 'local'
+// Determine the environment from the command line or default to 'local'.
 const ENV = (process.env.TEST_ENV || "local") as keyof typeof environments;
 
 export default defineConfig({
   testDir: "./tests/specs",
-  /* Run tests in files in parallel */
+  /* Run tests in files in parallel. */
   fullyParallel: true,
   /* Fail the build on CI if you accidentally left test.only in the source code. */
   forbidOnly: !!process.env.CI,
-  /* Retry on CI only */
+  /* Retry on CI only. */
   retries: process.env.CI ? 4 : 0,
   /* Opt out of parallel tests on CI. */
   workers: process.env.CI ? 1 : undefined,
-  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters. */
   reporter: "html",
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
   use: {
     /* Base URL to use in actions like `await page.goto('/')`. */
     baseURL: environments[ENV],
 
-    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer. */
     trace: "on-first-retry",
   },
 
-  /* Configure projects for major desktop browsers */
+  /* Configure projects for major desktop browsers. */
   projects: [
     {
       name: "chromium",
@@ -88,7 +88,7 @@ export default defineConfig({
     // },
   ],
 
-  /* Run your local dev server before starting the tests */
+  /* Run your local dev server before starting the tests. */
   // webServer: {
   //   command: 'npm run start',
   //   url: 'http://127.0.0.1:3000',
diff --git a/frontend/tests/specs/landing-page.spec.ts b/frontend/tests/specs/landing-page.spec.ts
index 4cb35a0d8..5c75fa163 100644
--- a/frontend/tests/specs/landing-page.spec.ts
+++ b/frontend/tests/specs/landing-page.spec.ts
@@ -1,5 +1,5 @@
-import { expect, test, LandingPage } from "../fixtures/page-fixtures";
 import AxeBuilder from "@axe-core/playwright";
+import { LandingPage, expect, test } from "../fixtures/page-fixtures";
 
 test.describe("Landing Page", () => {
   // Initialize page before each test, wait for the landing splash to be visible.
@@ -9,7 +9,7 @@ test.describe("Landing Page", () => {
     await landingSplash.waitFor({ state: "visible" });
   });
 
-  // Test accessibility of the landing page (skip this test for now)
+  // Test accessibility of the landing page (skip this test for now).
   test.skip("should not have any detectable accessibility issues", async ({
     landingPage,
   }, testInfo) => {