1 files changed, 67 insertions, 0 deletions
diff --git a/pydis_site/apps/api/serializers.py b/pydis_site/apps/api/serializers.py
index 1f19a371..905a7f82 100644
--- a/pydis_site/apps/api/serializers.py
+++ b/pydis_site/apps/api/serializers.py
@@ -1,3 +1,5 @@
+"""Converters from Django models to data interchange formats and back."""
+
 from rest_framework.serializers import ModelSerializer, PrimaryKeyRelatedField, ValidationError
 from rest_framework_bulk import BulkSerializerMixin
 
@@ -14,6 +16,8 @@ from .models import (
 
 
 class BotSettingSerializer(ModelSerializer):
+    """A class providing (de-)serialization of `BotSetting` instances."""
+
     class Meta:
         """Metadata defined for the Django REST Framework."""
 
@@ -22,6 +26,14 @@ class BotSettingSerializer(ModelSerializer):
 
 
 class DeletedMessageSerializer(ModelSerializer):
+    """
+    A class providing (de-)serialization of `DeletedMessage` instances.
+
+    The serializer generally requires a valid `deletion_context` to be
+    given, which should be created beforehand. See the `DeletedMessage`
+    model for more information.
+    """
+
     author = PrimaryKeyRelatedField(
         queryset=User.objects.all()
     )
@@ -44,6 +56,8 @@ class DeletedMessageSerializer(ModelSerializer):
 
 
 class MessageDeletionContextSerializer(ModelSerializer):
+    """A class providing (de-)serialization of `MessageDeletionContext` instances."""
+
     deletedmessage_set = DeletedMessageSerializer(many=True)
 
     class Meta:
@@ -54,6 +68,14 @@ class MessageDeletionContextSerializer(ModelSerializer):
         depth = 1
 
     def create(self, validated_data):
+        """
+        Return a `MessageDeletionContext` based on the given data.
+
+        In addition to the normal attributes expected by the `MessageDeletionContext` model
+        itself, this serializer also allows for passing the `deletedmessage_set` element
+        which contains messages that were deleted as part of this context.
+        """
+
         messages = validated_data.pop('deletedmessage_set')
         deletion_context = MessageDeletionContext.objects.create(**validated_data)
         for message in messages:
@@ -66,6 +88,8 @@ class MessageDeletionContextSerializer(ModelSerializer):
 
 
 class DocumentationLinkSerializer(ModelSerializer):
+    """A class providing (de-)serialization of `DocumentationLink` instances."""
+
     class Meta:
         """Metadata defined for the Django REST Framework."""
 
@@ -74,6 +98,8 @@ class DocumentationLinkSerializer(ModelSerializer):
 
 
 class InfractionSerializer(ModelSerializer):
+    """A class providing (de-)serialization of `Infraction` instances."""
+
     class Meta:
         """Metadata defined for the Django REST Framework."""
 
@@ -83,6 +109,8 @@ class InfractionSerializer(ModelSerializer):
         )
 
     def validate(self, attrs):
+        """Validate data constraints for the given data and abort if it is invalid."""
+
         infr_type = attrs.get('type')
 
         expires_at = attrs.get('expires_at')
@@ -97,7 +125,15 @@ class InfractionSerializer(ModelSerializer):
 
 
 class ExpandedInfractionSerializer(InfractionSerializer):
+    """A class providing expanded (de-)serialization of `Infraction` instances.
+
+    In addition to the fields of `Infraction` objects themselves, this
+    serializer also attaches the `user` and `actor` fields when serializing.
+    """
+
     def to_representation(self, instance):
+        """Return the dictionary representation of this infraction."""
+
         ret = super().to_representation(instance)
 
         user = User.objects.get(id=ret['user'])
@@ -112,6 +148,8 @@ class ExpandedInfractionSerializer(InfractionSerializer):
 
 
 class LogEntrySerializer(ModelSerializer):
+    """A class providing (de-)serialization of `LogEntry` instances."""
+
     class Meta:
         """Metadata defined for the Django REST Framework."""
 
@@ -123,6 +161,8 @@ class LogEntrySerializer(ModelSerializer):
 
 
 class OffTopicChannelNameSerializer(ModelSerializer):
+    """A class providing (de-)serialization of `OffTopicChannelName` instances."""
+
     class Meta:
         """Metadata defined for the Django REST Framework."""
 
@@ -130,10 +170,21 @@ class OffTopicChannelNameSerializer(ModelSerializer):
         fields = ('name',)
 
     def to_representation(self, obj):
+        """
+        Return the representation of this `OffTopicChannelName`.
+
+        This only returns the name of the off topic channel name. As the model
+        only has a single attribute, it is unnecessary to create a nested dictionary.
+        Additionally, this allows off topic channel name routes to simply return an
+        array of names instead of objects, saving on bandwidth.
+        """
+
         return obj.name
 
 
 class SnakeFactSerializer(ModelSerializer):
+    """A class providing (de-)serialization of `SnakeFact` instances."""
+
     class Meta:
         """Metadata defined for the Django REST Framework."""
 
@@ -142,6 +193,8 @@ class SnakeFactSerializer(ModelSerializer):
 
 
 class SnakeIdiomSerializer(ModelSerializer):
+    """A class providing (de-)serialization of `SnakeIdiom` instances."""
+
     class Meta:
         """Metadata defined for the Django REST Framework."""
 
@@ -150,6 +203,8 @@ class SnakeIdiomSerializer(ModelSerializer):
 
 
 class SnakeNameSerializer(ModelSerializer):
+    """A class providing (de-)serialization of `SnakeName` instances."""
+
     class Meta:
         """Metadata defined for the Django REST Framework."""
 
@@ -158,6 +213,8 @@ class SnakeNameSerializer(ModelSerializer):
 
 
 class SpecialSnakeSerializer(ModelSerializer):
+    """A class providing (de-)serialization of `SpecialSnake` instances."""
+
     class Meta:
         """Metadata defined for the Django REST Framework."""
 
@@ -166,6 +223,8 @@ class SpecialSnakeSerializer(ModelSerializer):
 
 
 class ReminderSerializer(ModelSerializer):
+    """A class providing (de-)serialization of `Reminder` instances."""
+
     author = PrimaryKeyRelatedField(queryset=User.objects.all())
 
     class Meta:
@@ -176,6 +235,8 @@ class ReminderSerializer(ModelSerializer):
 
 
 class RoleSerializer(ModelSerializer):
+    """A class providing (de-)serialization of `Role` instances."""
+
     class Meta:
         """Metadata defined for the Django REST Framework."""
 
@@ -184,6 +245,8 @@ class RoleSerializer(ModelSerializer):
 
 
 class TagSerializer(ModelSerializer):
+    """A class providing (de-)serialization of `Tag` instances."""
+
     class Meta:
         """Metadata defined for the Django REST Framework."""
 
@@ -192,6 +255,8 @@ class TagSerializer(ModelSerializer):
 
 
 class UserSerializer(BulkSerializerMixin, ModelSerializer):
+    """A class providing (de-)serialization of `User` instances."""
+
     roles = PrimaryKeyRelatedField(many=True, queryset=Role.objects.all(), required=False)
 
     class Meta:
@@ -203,6 +268,8 @@ class UserSerializer(BulkSerializerMixin, ModelSerializer):
 
 
 class NominationSerializer(ModelSerializer):
+    """A class providing (de-)serialization of `Nomination` instances."""
+
     author = PrimaryKeyRelatedField(queryset=User.objects.all())
     user = PrimaryKeyRelatedField(queryset=User.objects.all())