fixup!: Adds documentation for the code

Author: xitij2000

openedx/core/djangoapps/agreements/api.py

@@ -244,6 +244,9 @@ def _user_signature_out_of_date(username, course_id):
 
 
 def get_user_agreements(user: User) -> Iterable[UserAgreementRecordData]:
+    """
+    Retrieves all the agreements that the specified user has acknowledged.
+    """
     for agreement_record in UserAgreementRecord.objects.filter(user=user):
         yield UserAgreementRecordData.from_model(agreement_record)
 
@@ -253,6 +256,12 @@ def get_user_agreement_record(
     agreement_type: str,
     agreement_update_timestamp: datetime = None,
 ) -> Optional[UserAgreementRecordData]:
+    """
+    Retrieve the user agreement record for the specified user and agreement type.
+
+    An agreement update timestamp can be provided to return a record only if it
+    was signed after that timestamp.
+    """
     try:
         record_query = UserAgreementRecord.objects.filter(
             user=user,
@@ -267,6 +276,10 @@ def get_user_agreement_record(
 
 
 def create_user_agreement_record(user: User, agreement_type: str) -> UserAgreementRecordData:
+    """
+    Creates a user agreement record if one doesn't already exist, or updates existing
+    record to current timestamp.
+    """
     record, _ = UserAgreementRecord.objects.update_or_create(
         user=user,
         agreement_type=agreement_type,
@@ -275,4 +288,3 @@ def create_user_agreement_record(user: User, agreement_type: str) -> UserAgreeme
         },
     )
     return UserAgreementRecordData.from_model(record)
-

openedx/core/djangoapps/agreements/models.py

@@ -86,4 +86,5 @@ class UserAgreementRecord(models.Model):
 
     class Meta:
         app_label = 'agreements'
+        # A user can only have a single record for a single agreement type.
         unique_together = [['user', 'agreement_type']]

openedx/core/djangoapps/agreements/serializers.py

@@ -3,7 +3,7 @@
 """
 from rest_framework import serializers
 
-from openedx.core.djangoapps.agreements.models import IntegritySignature, LTIPIISignature, UserAgreementRecord
+from openedx.core.djangoapps.agreements.models import IntegritySignature, LTIPIISignature
 from openedx.core.lib.api.serializers import CourseKeyField
 
 
@@ -33,4 +33,7 @@ class Meta:
         fields = ('username', 'course_id', 'lti_tools', 'created_at')
 
 class UserAgreementsSerializer(serializers.Serializer):
+    """
+    Serializer for UserAgreementRecord model
+    """
     accepted_at = serializers.DateTimeField()

openedx/core/djangoapps/agreements/views.py

@@ -1,16 +1,18 @@
 """
 Views served by the Agreements app
 """
-from os import times
 
+import edx_api_doc_tools as apidocs
 from django.conf import settings
 from django import forms
+from drf_yasg import openapi
 from rest_framework import status
 from rest_framework.views import APIView
 from rest_framework.response import Response
 from rest_framework.permissions import IsAuthenticated
 from opaque_keys.edx.keys import CourseKey
 
+
 from common.djangoapps.student import auth
 from common.djangoapps.student.roles import CourseStaffRole
 from openedx.core.djangoapps.agreements.api import (
@@ -165,11 +167,42 @@ def post(self, request, course_id):
 
 
 class UserAgreementsView(AuthenticatedAPIView):
+    """
+    Endpoint for the user agreements API.
+    """
 
     class QueryFilterForm(forms.Form):
+        """
+        Query parameters for the GET method.
+        """
         after = forms.DateTimeField(required=False)
 
+    @apidocs.schema(
+        parameters=[
+            apidocs.string_parameter(
+                'agreement_type',
+                apidocs.ParameterLocation.PATH,
+                description="Agreement ID/Type",
+            ),
+            openapi.Parameter(
+                'after',
+                apidocs.ParameterLocation.QUERY,
+                required=False,
+                type=openapi.TYPE_STRING,
+                format=openapi.FORMAT_DATETIME,
+                description="Return records after this date/time",
+            ),
+        ],
+        responses={
+            200: UserAgreementsSerializer,
+            400: "Bad Request",
+            404: "Not Found",
+        },
+    )
     def get(self, request, agreement_type):
+        """
+        Get a user's acknowledgement record for this agreement type.
+        """
         params = UserAgreementsView.QueryFilterForm(request.query_params)
         if not params.is_valid():
             return Response(status=status.HTTP_400_BAD_REQUEST)
@@ -179,7 +212,23 @@ def get(self, request, agreement_type):
         serializer = UserAgreementsSerializer(record)
         return Response(serializer.data)
 
+    @apidocs.schema(
+        parameters=[
+            apidocs.string_parameter(
+                'agreement_type',
+                apidocs.ParameterLocation.PATH,
+                description="Agreement ID/Type",
+            ),
+        ],
+        responses={
+            200: UserAgreementsSerializer,
+            400: "Bad Request",
+        },
+    )
     def post(self, request, agreement_type):
+        """
+        Marks a user's acknowledgement of this agreement type.
+        """
         record = create_user_agreement_record(request.user, agreement_type)
         serializer = UserAgreementsSerializer(record)
         return Response(serializer.data, status=status.HTTP_201_CREATED)