Document that dispatch should not be used for detail route method name

[lampwins]

Checklist

• [ x ] I have verified that that issue exists against the master branch of Django REST framework.
• [ x ] I have searched for similar issues in both open and closed tickets and cannot find a duplicate.
• [ x ] This is not a usage question. (Those should be directed to the discussion group instead.)
• [ x ] This cannot be dealt with as a third party library. (We prefer new functionality to be in the form of third party libraries where possible.)
• [ x ] I have reduced the issue to the simplest possible case.
• I have included a failing test as a pull request. (If you are unable to do so we can still accept the issue.)

Steps to reproduce

Create a simple ViewSet with a detail route with method name dispatch

class TestViewSet(ModelViewSet):
    queryset = Test.objects.all()
    serializer_class = serializers.TestSerializer
    filter_class = filters.TestFilter

    @detail_route(url_path='dispatch', methods=['post'])
    def dispatch(self, request, pk=None):

        return Response("hello", status=status.HTTP_200_ACCEPTED)

Expected behavior

Not really sure here as it is colliding with the dispatch method under the hood of DFR

Actual behavior

The DRF router exhibits very odd behavior but does not function in any useful manor. It looks like the base path for the ViewSet is lost so all requests result in a 404.

I am not entirely sure what is going on but I can speculate that the detail route method is overlapping with the detail route method of the base ViewSet class. After looking deeper into DRF I understand why this is probably happening and why it probably can't easily be fixed. However, I think it would be fair to document this to say that a detail route method name should not be named dispatch.

[tomchristie]

Given that this applies to any method name in APIView, I don't see any obvious way of addressing this in the documentation, other than mentioning that ViewSets inherit from APIView (which we do).

One option might be for us to link to http://www.cdrf.co/ in both the views and the viewsets documentation, perhaps?

[tomchristie]

Following up here... https://twitter.com/_tomchristie/status/936177036703518720

[lampwins]

Yeah, I understand why it has to be this way so anything that can enhance the documentation would be helpful IMHO. I am in favor of your proposition.