Fixed #8325 -- Reorganization and expansion of the login_required decorator docs to make it clearer how the redirect_field_name parameter works and improve the overall flow of the text. Thanks to Robert Reeves for the report.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14480 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/topics/auth.txt

@@ -693,7 +693,7 @@ login page::
 The login_required decorator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. function:: decorators.login_required()
+.. function:: decorators.login_required([redirect_field_name=REDIRECT_FIELD_NAME, login_url=None])
 
     As a shortcut, you can use the convenient
     :func:`~django.contrib.auth.decorators.login_required` decorator::
@@ -703,17 +703,33 @@ The login_required decorator
         @login_required
         def my_view(request):
             ...
+    
+    :func:`~django.contrib.auth.decorators.login_required` does the following:
 
-    :func:`~django.contrib.auth.decorators.login_required` also takes an
-    optional ``redirect_field_name`` parameter. Example::
+    * If the user isn't logged in, redirect to
+      :setting:`settings.LOGIN_URL <LOGIN_URL>`, passing the current absolute
+      path in the query string. Example: ``/accounts/login/?next=/polls/3/``.
 
+    * If the user is logged in, execute the view normally. The view code is
+      free to assume the user is logged in.
+
+    By default, the path that the user should be redirected to upon
+    successful authentication is stored in a query string parameter called
+    ``"next"``. If you would prefer to use a different name for this parameter,
+    :func:`~django.contrib.auth.decorators.login_required` takes an
+    optional ``redirect_field_name`` parameter::
 
         from django.contrib.auth.decorators import login_required
 
-        @login_required(redirect_field_name='redirect_to')
+        @login_required(redirect_field_name='my_redirect_field')
         def my_view(request):
             ...
 
+    Note that if you provide a value to ``redirect_field_name``, you will most
+    likely need to customize your login template as well, since the template
+    context variable which stores the redirect path will use the value of
+    ``redirect_field_name`` as it's key rather than ``"next"`` (the default).
+
     .. versionadded:: 1.3
 
     :func:`~django.contrib.auth.decorators.login_required` also takes an
@@ -725,24 +741,11 @@ The login_required decorator
         def my_view(request):
             ...
 
-    :func:`~django.contrib.auth.decorators.login_required` does the following:
-
-        * If the user isn't logged in, redirect to
-          :setting:`settings.LOGIN_URL <LOGIN_URL>` (``/accounts/login/`` by
-          default), passing the current absolute URL in the query string. The
-          name of the GET argument is determined by the ``redirect_field_name``
-          argument provided to the decorator. The default argument name is
-          ``next``. For example:
-          ``/accounts/login/?next=/polls/3/``.
-
-        * If the user is logged in, execute the view normally. The view code is
-          free to assume the user is logged in.
-
-Note that if you don't specify the ``login_url`` parameter, you'll need to map
-the appropriate Django view to :setting:`settings.LOGIN_URL <LOGIN_URL>`. For
-example, using the defaults, add the following line to your URLconf::
+    Note that if you don't specify the ``login_url`` parameter, you'll need to map
+    the appropriate Django view to :setting:`settings.LOGIN_URL <LOGIN_URL>`. For
+    example, using the defaults, add the following line to your URLconf::
 
-    (r'^accounts/login/$', 'django.contrib.auth.views.login'),
+        (r'^accounts/login/$', 'django.contrib.auth.views.login'),
 
 .. function:: views.login(request, [template_name, redirect_field_name, authentication_form])