GitHub link in toolbar

2 files changed, 19 insertions, 6 deletions

diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md
index c8ccb08b..c22d6d8b 100644
--- a/docs/api-guide/exceptions.md
+++ b/docs/api-guide/exceptions.md
@@ -8,7 +8,7 @@
 
 ## Exception handling in REST framework views
 
-REST framework's views handle various exceptions, and deal with returning appropriate error responses for you.
+REST framework's views handle various exceptions, and deal with returning appropriate error responses.
 
 The handled exceptions are:
 
@@ -16,9 +16,9 @@ The handled exceptions are:
 * Django's `Http404` exception.
 * Django's `PermissionDenied` exception.
 
-In each case, REST framework will return a response, rendering it to an appropriate content-type.
+In each case, REST framework will return a response with an appropriate status code and content-type.  The body of the response will include any additional details regarding the nature of the error.
 
-By default all error messages will include a key `details` in the body of the response, but other keys may also be included.
+By default all error responses will include a key `details` in the body of the response, but other keys may also be included.
 
 For example, the following request:
 
diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md
index be22eefe..e0f3583f 100644
--- a/docs/api-guide/permissions.md
+++ b/docs/api-guide/permissions.md
@@ -12,7 +12,7 @@ Permission checks are always run at the very start of the view, before any other
 
 ## How permissions are determined
 
-Permissions in REST framework are always defined as a list of permission classes.  Before running the main body of the view, each permission in the list is checked.
+Permissions in REST framework are always defined as a list of permission classes.  Before running the main body of the view each permission in the list is checked.
 
 If any permission check fails an `exceptions.PermissionDenied` exception will be raised, and the main body of the view will not run.
 
@@ -73,7 +73,18 @@ This permission is suitable if you want to your API to allow read permissions to
 
 ## DjangoModelPermissions
 
-This permission class ties into Django's standard `django.contrib.auth` model permissions.  When applied to a view that has a `.model` property, permission will only be granted if the user
+This permission class ties into Django's standard `django.contrib.auth` [model permissions][contribauth].  When applied to a view that has a `.model` property, authorization will only be granted if the user has the relevant model permissions assigned.
+
+* `POST` requests require the user to have the `add` permission on the model.
+* `PUT` and `PATCH` requests require the user to have the `change` permission on the model.
+* `DELETE` requests require the user to have the `delete` permission on the model.
+ 
+The default behaviour can also be overridden to support custom model permissions.  For example, you might want to include a `view` model permission for `GET` requests.
+
+To use custom model permissions, override `DjangoModelPermissions` and set the `.perms_map` property.  Refer to the source code for details.
+
+The `DjangoModelPermissions` class also supports object-level permissions.  Third-party authorization backends such as [django-guardian][guardian] should work just fine with `DjangoModelPermissions` without any custom configuration required.
+
 
 ## Custom permissions
 
@@ -84,4 +95,6 @@ The method should return `True` if the request should be granted access, and `Fa
 
 [cite]: https://developer.apple.com/library/mac/#documentation/security/Conceptual/AuthenticationAndAuthorizationGuide/Authorization/Authorization.html
 [authentication]: authentication.md
-[throttling]: throttling.md
\ No newline at end of file
+[throttling]: throttling.md
+[contribauth]: https://docs.djangoproject.com/en/1.0/topics/auth/#permissions
+[guardian]: https://github.com/lukaszb/django-guardian
\ No newline at end of file