Flesh out authentication docs

docs/api-guide/authentication.md

@@ -6,12 +6,21 @@ REST framework provides a number of authentication policies out of the box, and
 
 Authentication will run the first time either the `request.user` or `request.auth` properties are accessed, and determines how those properties are initialized.
 
+## How authentication is determined
+
+Authentication is always set as a list of classes.  REST framework will attempt to authenticate with each class in the list, and will set `request.user` and `request.auth` using the return value of the first class that successfully authenticates.
+
+If no class authenticates, `request.user` will be set to an instance of `django.contrib.auth.models.AnonymousUser`, and `request.auth` will be set to `None`.
+
+The value of `request.user` and `request.auth` for unauthenticated requests can be modified using the [`UNAUTHENTICATED_USER`][UNAUTHENTICATED_USER] and [`UNAUTHENTICATED_TOKEN`][UNAUTHENTICATED_TOKEN] settings.
+
 ## Setting the authentication policy
 
-The default authentication policy may be set globally, using the `DEFAULT_AUTHENTICATION_CLASSES` setting.  For example.
+The default authentication policy may be set globally, using the `DEFAULT_AUTHENTICATION` setting.  For example.
 
     API_SETTINGS = {
-        'DEFAULT_AUTHENTICATION_CLASSES': (
+        'DEFAULT_AUTHENTICATION': (
+            'djangorestframework.authentication.UserBasicAuthentication',
             'djangorestframework.authentication.SessionAuthentication',
         )
     }
@@ -19,7 +28,7 @@ The default authentication policy may be set globally, using the `DEFAULT_AUTHEN
 You can also set the authentication policy on a per-view basis, using the `APIView` class based views.
 
     class ExampleView(APIView):
-        authentication_classes = (SessionAuthentication,)
+        authentication_classes = (SessionAuthentication, UserBasicAuthentication)
 
         def get(self, request, format=None):
             content = {
@@ -30,7 +39,10 @@ You can also set the authentication policy on a per-view basis, using the `APIVi
 
 Or, if you're using the `@api_view` decorator with function based views.
 
-    @api_view(allowed=('GET',), authentication_classes=(SessionAuthentication,))
+    @api_view(
+        allowed=('GET',),
+        authentication_classes=(SessionAuthentication, UserBasicAuthentication)
+    )
     def example_view(request, format=None):
         content = {
             'user': unicode(request.user),  # `django.contrib.auth.User` instance. 
@@ -86,3 +98,5 @@ To implement a custom authentication policy, subclass `BaseAuthentication` and o
 [oauth]: http://oauth.net/2/
 [permission]: permissions.md
 [throttling]: throttling.md
+[UNAUTHENTICATED_USER]: settings.md#UNAUTHENTICATED_USER
+[UNAUTHENTICATED_TOKEN]: settings.md#UNAUTHENTICATED_TOKEN

docs/api-guide/settings.md

@@ -70,24 +70,40 @@ Default: `djangorestframework.pagination.PaginationSerializer`
 
 ## FORMAT_SUFFIX_KWARG
 
-Default: `format`
+Default: `'format'`
 
-## UNAUTHENTICATED_USER_CLASS
+## UNAUTHENTICATED_USER
+
+The class that should be used to initialize `request.user` for unauthenticated requests.
 
 Default: `django.contrib.auth.models.AnonymousUser`
 
+## UNAUTHENTICATED_USER
+
+The class that should be used to initialize `request.auth` for unauthenticated requests.
+
+Default: `None`
+
 ## FORM_METHOD_OVERRIDE
 
-Default: `_method`
+The name of a form field that may be used to override the HTTP method of the form.
+
+Default: `'_method'`
 
 ## FORM_CONTENT_OVERRIDE
 
-Default: `_content`
+The name of a form field that may be used to override the content of the form payload.
+
+Default: `'_content'`
 
 ## FORM_CONTENTTYPE_OVERRIDE
 
-Default: `_content_type`
+The name of a form field that may be used to override the content type of the form payload.
+
+Default: `'_content_type'`
 
 ## URL_ACCEPT_OVERRIDE
 
-Default: `_accept`
+The name of a URL parameter that may be used to override the HTTP `Accept` header.
+
+Default: `'_accept'`