Tidying up docs

docs/api-guide/authentication.md

@@ -6,13 +6,17 @@ 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.
 
+The `request.user` property will typically be set to an instance of the `contrib.auth` package's `User` class.
+
+The `request.auth` property is used for any additional authentication information, for example, it may be used to represent an authentication token that the request was signed with.  
+
 ## 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.
+The value of `request.user` and `request.auth` for unauthenticated requests can be modified using the `UNAUTHENTICATED_USER` and `UNAUTHENTICATED_TOKEN` settings.
 
 ## Setting the authentication policy
 
@@ -98,5 +102,3 @@ 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/reverse.md

@@ -11,7 +11,7 @@ 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 use to easily do things like markup HTML representations with hyperlinks.
+* It makes it easy to do things like markup HTML representations with hyperlinks.
 
 REST framework provides two utility functions to make it more simple to return absolute URIs from your Web API.
 

docs/api-guide/settings.md

@@ -1,6 +1,7 @@
 # Settings
 
-Settings for REST framework are all namespaced in the `API_SETTINGS` setting.
+Configuration for REST framework is all namespaced inside the `API_SETTINGS` setting.
+
 For example your project's `settings.py` file might look like this:
 
     API_SETTINGS = {
@@ -54,10 +55,14 @@ Default if `DEBUG` is `False`:
 
 ## DEFAULT_PERMISSIONS
 
+A list or tuple of permission classes, that determines the default set of permissions checked at the start of a view.
+
 Default: `()`
 
 ## DEFAULT_THROTTLES
 
+A list or tuple of throttle classes, that determines the default set of throttles checked at the start of a view.
+
 Default: `()`
 
 ## DEFAULT_MODEL_SERIALIZER
@@ -78,7 +83,7 @@ The class that should be used to initialize `request.user` for unauthenticated r
 
 Default: `django.contrib.auth.models.AnonymousUser`
 
-## UNAUTHENTICATED_USER
+## UNAUTHENTICATED_TOKEN
 
 The class that should be used to initialize `request.auth` for unauthenticated requests.
 
@@ -88,17 +93,23 @@ Default: `None`
 
 The name of a form field that may be used to override the HTTP method of the form.
 
+If the value of this setting is `None` then form method overloading will be disabled.
+
 Default: `'_method'`
 
 ## FORM_CONTENT_OVERRIDE
 
-The name of a form field that may be used to override the content of the form payload.
+The name of a form field that may be used to override the content of the form payload.  Must be used together with `FORM_CONTENTTYPE_OVERRIDE`.
+
+If either setting is `None` then form content overloading will be disabled.
 
 Default: `'_content'`
 
 ## FORM_CONTENTTYPE_OVERRIDE
 
-The name of a form field that may be used to override the content type of the form payload.
+The name of a form field that may be used to override the content type of the form payload.  Must be used together with `FORM_CONTENT_OVERRIDE`.
+
+If either setting is `None` then form content overloading will be disabled.
 
 Default: `'_content_type'`
 
@@ -106,4 +117,6 @@ Default: `'_content_type'`
 
 The name of a URL parameter that may be used to override the HTTP `Accept` header.
 
+If the value of this setting is `None` then URL accept overloading will be disabled.
+
 Default: `'_accept'`