Merge branch 'version-3.1' into oauth_as_package

Conflicts:
	requirements-test.txt
	rest_framework/compat.py
	tests/settings.py
	tox.ini

1 files changed, 21 insertions, 3 deletions

diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md
index e61dcfa9..467ad970 100644
--- a/docs/api-guide/exceptions.md
+++ b/docs/api-guide/exceptions.md
@@ -1,4 +1,4 @@
-<a class="github" href="exceptions.py"></a>
+source: exceptions.py
 
 # Exceptions
 
@@ -100,7 +100,7 @@ For example, if your API relies on a third party service that may sometimes be u
 
 **Signature:** `ParseError(detail=None)`
 
-Raised if the request contains malformed data when accessing `request.DATA` or `request.FILES`.
+Raised if the request contains malformed data when accessing `request.data`.
 
 By default this exception results in a response with the HTTP status code "400 Bad Request".
 
@@ -140,7 +140,7 @@ By default this exception results in a response with the HTTP status code "405 M
 
 **Signature:** `UnsupportedMediaType(media_type, detail=None)`
 
-Raised if there are no parsers that can handle the content type of the request data when accessing `request.DATA` or `request.FILES`.
+Raised if there are no parsers that can handle the content type of the request data when accessing `request.data`.
 
 By default this exception results in a response with the HTTP status code "415 Unsupported Media Type".
 
@@ -152,5 +152,23 @@ Raised when an incoming request fails the throttling checks.
 
 By default this exception results in a response with the HTTP status code "429 Too Many Requests".
 
+## ValidationError
+
+**Signature:** `ValidationError(detail)`
+
+The `ValidationError` exception is slightly different from the other `APIException` classes:
+
+* The `detail` argument is mandatory, not optional.
+* The `detail` argument may be a list or dictionary of error details, and may also be a nested data structure.
+* By convention you should import the serializers module and use a fully qualified `ValidationError` style, in order to differentiate it from Django's built-in validation error. For example. `raise serializers.ValidationError('This field must be an integer value.')`
+
+The `ValidationError` class should be used for serializer and field validation, and by validator classes. It is also raised when calling `serializer.is_valid` with the `raise_exception` keyword argument:
+
+    serializer.is_valid(raise_exception=True)
+
+The generic views use the `raise_exception=True` flag, which means that you can override the style of validation error responses globally in your API. To do so, use a custom exception handler, as described above.
+
+By default this exception results in a response with the HTTP status code "400 Bad Request".
+
 [cite]: http://www.doughellmann.com/articles/how-tos/python-exception-handling/index.html
 [authentication]: authentication.md