Merge

2 files changed, 25 insertions, 16 deletions

diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md
index 072a2e79..7884c2e9 100644
--- a/docs/api-guide/routers.md
+++ b/docs/api-guide/routers.md
@@ -35,12 +35,12 @@ The example above would generate the following URL patterns:
 * URL pattern: `^accounts/$`  Name: `'account-list'`
 * URL pattern: `^accounts/{pk}/$`  Name: `'account-detail'`
 
-### Extra link and actions
+### Registering additional routes
 
-Any methods on the viewset decorated with `@link` or `@action` will also be routed.
+Any methods on the viewset decorated with `@detail_route` or `@list_route` will also be routed.
 For example, given a method like this on the `UserViewSet` class:
 
-    @action(permission_classes=[IsAdminOrIsSelf])
+    @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf])
     def set_password(self, request, pk=None):
         ...
 
@@ -52,7 +52,7 @@ The following URL pattern would additionally be generated:
 
 ## SimpleRouter
 
-This router includes routes for the standard set of `list`, `create`, `retrieve`, `update`, `partial_update` and `destroy` actions.  The viewset can also mark additional methods to be routed, using the `@link` or `@action` decorators.
+This router includes routes for the standard set of `list`, `create`, `retrieve`, `update`, `partial_update` and `destroy` actions.  The viewset can also mark additional methods to be routed, using the `@detail_route` or `@list_route` decorators.
 
 <table border=1>
     <tr><th>URL Style</th><th>HTTP Method</th><th>Action</th><th>URL Name</th></tr>
@@ -62,8 +62,8 @@ This router includes routes for the standard set of `list`, `create`, `retrieve`
     <tr><td>PUT</td><td>update</td></tr>
     <tr><td>PATCH</td><td>partial_update</td></tr>
     <tr><td>DELETE</td><td>destroy</td></tr>
-    <tr><td rowspan=2>{prefix}/{lookup}/{methodname}/</td><td>GET</td><td>@link decorated method</td><td rowspan=2>{basename}-{methodname}</td></tr>
-    <tr><td>POST</td><td>@action decorated method</td></tr>
+    <tr><td rowspan=2>{prefix}/{lookup}/{methodname}/</td><td>GET</td><td>@detail_route decorated method</td><td rowspan=2>{basename}-{methodname}</td></tr>
+    <tr><td>POST</td><td>@detail_route decorated method</td></tr>
 </table>
 
 By default the URLs created by `SimpleRouter` are appended with a trailing slash.
@@ -86,8 +86,8 @@ This router is similar to `SimpleRouter` as above, but additionally includes a d
     <tr><td>PUT</td><td>update</td></tr>
     <tr><td>PATCH</td><td>partial_update</td></tr>
     <tr><td>DELETE</td><td>destroy</td></tr>
-    <tr><td rowspan=2>{prefix}/{lookup}/{methodname}/[.format]</td><td>GET</td><td>@link decorated method</td><td rowspan=2>{basename}-{methodname}</td></tr>
-    <tr><td>POST</td><td>@action decorated method</td></tr>
+    <tr><td rowspan=2>{prefix}/{lookup}/{methodname}/[.format]</td><td>GET</td><td>@detail_route decorated method</td><td rowspan=2>{basename}-{methodname}</td></tr>
+    <tr><td>POST</td><td>@detail_route decorated method</td></tr>
 </table>
 
 As with `SimpleRouter` the trailing slashes on the URL routes can be removed by setting the `trailing_slash` argument to `False` when instantiating the router.
diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md
index 0c68afb0..95efc229 100644
--- a/docs/api-guide/viewsets.md
+++ b/docs/api-guide/viewsets.md
@@ -92,14 +92,16 @@ The default routers included with REST framework will provide routes for a stand
         def destroy(self, request, pk=None):
             pass
 
-If you have ad-hoc methods that you need to be routed to, you can mark them as requiring routing using the `@link` or `@action` decorators.  The `@link` decorator will route `GET` requests, and the `@action` decorator will route `POST` requests.
+If you have ad-hoc methods that you need to be routed to, you can mark them as requiring routing using the `@detail_route` or `@list_route` decorators.
+
+The `@detail_route` decorator contains `pk` in its URL pattern and is intended for methods which require a single instance. The `@list_route` decorator is intended for methods which operate on a list of objects.
 
 For example:
 
     from django.contrib.auth.models import User
-    from rest_framework import viewsets
     from rest_framework import status
-    from rest_framework.decorators import action
+    from rest_framework import viewsets
+    from rest_framework.decorators import detail_route, list_route
     from rest_framework.response import Response
     from myapp.serializers import UserSerializer, PasswordSerializer
 
@@ -110,7 +112,7 @@ For example:
         queryset = User.objects.all()
         serializer_class = UserSerializer
 
-        @action()
+        @detail_route(methods=['post'])
         def set_password(self, request, pk=None):
             user = self.get_object()
             serializer = PasswordSerializer(data=request.DATA)
@@ -122,15 +124,22 @@ For example:
                 return Response(serializer.errors,
                                 status=status.HTTP_400_BAD_REQUEST)
 
-The `@action` and `@link` decorators can additionally take extra arguments that will be set for the routed view only.  For example...
+        @list_route()
+        def recent_users(self, request):
+            recent_users = User.objects.all().order('-last_login')
+            page = self.paginate_queryset(recent_users)
+            serializer = self.get_pagination_serializer(page)
+            return Response(serializer.data)
+
+The decorators can additionally take extra arguments that will be set for the routed view only.  For example...
 
-        @action(permission_classes=[IsAdminOrIsSelf])
+        @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf])
         def set_password(self, request, pk=None):
            ...
 
-The `@action` decorator will route `POST` requests by default, but may also accept other HTTP methods, by using the `method` argument.  For example:
+By default, the decorators will route `GET` requests, but may also accept other HTTP methods, by using the `methods` argument.  For example:
 
-        @action(methods=['POST', 'DELETE'])
+        @detail_route(methods=['post', 'delete'])
         def unset_password(self, request, pk=None):
            ...
 ---