Cleanup of reverse docs

1 files changed, 21 insertions, 10 deletions

diff --git a/docs/howto/reverse.rst b/docs/howto/reverse.rst
index 73b8fa4d..0a7af0e9 100644
--- a/docs/howto/reverse.rst
+++ b/docs/howto/reverse.rst
@@ -1,23 +1,32 @@
 Returning URIs from your Web APIs
 =================================
 
-As a rule, it's probably better practice to return absolute URIs from you web APIs, e.g. "http://example.com/foobar", rather than returning relative URIs, e.g. "/foobar".
+As a rule, it's probably better practice to return absolute URIs from you web
+APIs, e.g. "http://example.com/foobar", rather than returning relative URIs,
+e.g. "/foobar".
 
 The advantages of doing so are:
 
 * It's more explicit.
 * It leaves less work for your API clients.
-* There's no ambiguity about the meaning of the string when it's found in representations such as JSON that do not have a native URI type.
-* It allows us to easily do things like markup HTML representations with hyperlinks.
+* There's no ambiguity about the meaning of the string when it's found in
+  representations such as JSON that do not have a native URI type.
+* It allows us to easily do things like markup HTML representations
+  with hyperlinks.
 
-Django REST framework provides two utility functions to make it simpler to return absolute URIs from your Web API.
+Django REST framework provides two utility functions to make it simpler to
+return absolute URIs from your Web API.
 
-There's no requirement for you to use them, but if you do then the self-describing API will be able to automatically hyperlink its output for you, which makes browsing the API much easier.
+There's no requirement for you to use them, but if you do then the
+self-describing API will be able to automatically hyperlink its output for you,
+which makes browsing the API much easier.
 
-reverse(viewname, request, ...)
+reverse(viewname, ..., request=None)
 -------------------------------
 
-The :py:func:`~reverse.reverse` function has the same behavior as `django.core.urlresolvers.reverse`_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port::
+The `reverse` function has the same behavior as
+`django.core.urlresolvers.reverse`_, except that it optionally takes a request
+keyword argument, which it uses to return a fully qualified URL.
 
     from djangorestframework.reverse import reverse
     from djangorestframework.views import View
@@ -25,15 +34,17 @@ The :py:func:`~reverse.reverse` function has the same behavior as `django.core.u
     class MyView(View):
         def get(self, request):
             context = {
-                'url': reverse('year-summary', request, args=[1945])
+                'url': reverse('year-summary', args=[1945], request=request)
             }
 
             return Response(context)
 
-reverse_lazy(viewname, request, ...)
+reverse_lazy(viewname, ..., request=None)
 ------------------------------------
 
-The :py:func:`~reverse.reverse_lazy` function has the same behavior as `django.core.urlresolvers.reverse_lazy`_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port.
+The `reverse_lazy` function has the same behavior as
+`django.core.urlresolvers.reverse_lazy`_, except that it optionally takes a
+request keyword argument, which it uses to return a fully qualified URL.
 
 .. _django.core.urlresolvers.reverse: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse
 .. _django.core.urlresolvers.reverse_lazy: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse-lazy