REST: Add additional documentation

As noted in the Django REST Framework docs [1], views that support
multiple methods can and should split their documentation using
'method:' style delimiters. Do just this.

[1] https://www.django-rest-framework.org/topics/documenting-your-api/#documenting-your-views

Signed-off-by: Stephen Finucane <stephen@that.guru>

diff --git a/patchwork/api/check.py b/patchwork/api/check.py
index 48019e7282a3f93c25b848b36eee46bb02e2f3b9..4771455fd808d65eefc76b0ae2c7cb96548ab874 100644 (file)
--- a/patchwork/api/check.py
+++ b/patchwork/api/check.py
@@ -74,7 +74,13 @@ class CheckMixin(object):
 
 
 class CheckListCreate(CheckMixin, ListCreateAPIView):
-    """List or create checks."""
+    """
+    get:
+    List checks.
+
+    post:
+    Create a check.
+    """
 
     lookup_url_kwarg = 'patch_id'
     ordering = 'id'

diff --git a/patchwork/api/index.py b/patchwork/api/index.py
index 2266635c086700937de4a84f39c5e03e53affbb5..45485c9106f6eb4218ddffb04d0a11f09242379d 100644 (file)
--- a/patchwork/api/index.py
+++ b/patchwork/api/index.py
@@ -11,6 +11,7 @@ from rest_framework.views import APIView
 class IndexView(APIView):
 
     def get(self, request, *args, **kwargs):
+        """List API resources."""
         return Response({
             'projects': reverse('api-project-list', request=request),
             'users': reverse('api-user-list', request=request),

diff --git a/patchwork/api/patch.py b/patchwork/api/patch.py
index 6367dd5d9014f451a705a7d105593e320d459319..523378daa2cbab8c07ebd40ef51bcb129e61e24d 100644 (file)
--- a/patchwork/api/patch.py
+++ b/patchwork/api/patch.py
@@ -188,8 +188,16 @@ class PatchList(ListAPIView):
 
 
 class PatchDetail(RetrieveUpdateAPIView):
-    """Show a patch."""
+    """
+    get:
+    Show a patch.
+
+    patch:
+    Update a patch.
 
+    put:
+    Update a patch.
+    """
     permission_classes = (PatchworkPermission,)
     serializer_class = PatchDetailSerializer
 

diff --git a/patchwork/api/project.py b/patchwork/api/project.py
index 22fb1c4e73f57c46a852150b7acf598f27e49afb..d7bb1f21cd093026ab8f1c873d2ae05b4f1bbdbf 100644 (file)
--- a/patchwork/api/project.py
+++ b/patchwork/api/project.py
@@ -74,6 +74,15 @@ class ProjectList(ProjectMixin, ListAPIView):
 
 
 class ProjectDetail(ProjectMixin, RetrieveUpdateAPIView):
-    """Show a project."""
+    """
+    get:
+    Show a project.
+
+    patch:
+    Update a project.
+
+    put:
+    Update a project.
+    """
 
     pass

diff --git a/patchwork/api/user.py b/patchwork/api/user.py
index e11bed4ba079deaddf94f77e4b21a25f4ef4b9bd..29944e228675ecfdd257a5d5a417143224ae84b7 100644 (file)
--- a/patchwork/api/user.py
+++ b/patchwork/api/user.py
@@ -48,6 +48,15 @@ class UserList(UserMixin, ListAPIView):
 
 
 class UserDetail(UserMixin, RetrieveUpdateAPIView):
-    """Show a user."""
+    """
+    get:
+    Show a user.
+
+    patch:
+    Update a user.
+
+    put:
+    Update a user.
+    """
 
     pass