Improve the docstring on @action

rest_framework/decorators.py

@@ -124,8 +124,23 @@ def action(methods=None, detail=None, url_path=None, url_name=None, **kwargs):
     """
     Mark a ViewSet method as a routable action.
 
-    Set the `detail` boolean to determine if this action should apply to
-    instance/detail requests or collection/list requests.
+    `@action`-decorated functions will be endowed with a `mapping` property,
+    a `MethodMapper` that can be used to add additional method-based behaviors
+    on the routed action.
+
+    :param methods: A list of HTTP method names this action responds to.
+                    Defaults to GET only.
+    :param detail: Required. Determines whether this action applies to
+                   instance/detail requests or collection/list requests.
+    :param url_path: Define the URL segment for this action. Defaults to the
+                     name of the method decorated.
+    :param url_name: Define the internal (`reverse`) URL name for this action.
+                     Defaults to the name of the method decorated with underscores
+                     replaced with dashes.
+    :param kwargs: Additional properties to set on the view.  This can be used
+                   to override viewset-level *_classes settings, equivalent to
+                   how the `@renderer_classes` etc. decorators work for function-
+                   based API views.
     """
     methods = ['get'] if (methods is None) else methods
     methods = [method.lower() for method in methods]
@@ -144,6 +159,10 @@ def decorator(func):
         func.detail = detail
         func.url_path = url_path if url_path else func.__name__
         func.url_name = url_name if url_name else func.__name__.replace('_', '-')
+
+        # These kwargs will end up being passed to `ViewSet.as_view()` within
+        # the router, which eventually delegates to Django's CBV `View`,
+        # which assigns them as instance attributes for each request.
         func.kwargs = kwargs
 
         # Set descriptive arguments for viewsets