Docs for FileUploadParser

3 files changed, 14 insertions, 5 deletions

diff --git a/docs/api-guide/parsers.md b/docs/api-guide/parsers.md
index 20518647..7d2c056e 100644
--- a/docs/api-guide/parsers.md
+++ b/docs/api-guide/parsers.md
@@ -104,13 +104,18 @@ You will typically want to use both `FormParser` and `MultiPartParser` together
 
 ## FileUploadParser
 
-Parses raw file upload content. Returns a `DataAndFiles` object. Since we expect the whole request body to be a file content `request.DATA` will be None, and `request.FILES` will contain the only one key `'file'` matching the uploaded file.
+Parses raw file upload content.  The `request.DATA` property will be an empty `QueryDict`, and `request.FILES` will be a dictionary with a single key `'file'` containing the uploaded file.
 
-The `filename` property of uploaded file would be set to the result of `.get_filename()` method. By default it tries first to take it's value from the `filename` URL kwarg, and then from `Content-Disposition` HTTP header. You can implement other behaviour be overriding this method.
+If the view used with `FileUploadParser` is called with a `filename` URL keyword argument, then that argument will be used as the filename.  If it is called without a `filename` URL keyword argument, then the client must set the filename in the `Content-Disposition` HTTP header.  For example `Content-Disposition: attachment; filename=upload.jpg`.
 
-Note that since this parser's `media_type` matches every HTTP request it imposes restrictions on usage in combination with other parsers for the same API view.
+**.media_type**: `*/*`
+
+##### Notes:
 
-Basic usage expamle:
+* The `FileUploadParser` is for usage with native clients that can upload the file as a raw data request.  For web-based uploads, or for native clients with multipart upload support, you should use the `MultiPartParser` parser instead.
+* Since this parser's `media_type` matches any content type, `FileUploadParser` should generally be the only parser set on an API view.
+
+##### Basic usage example:
 
     class FileUploadView(views.APIView):
         parser_classes = (FileUploadParser,)
@@ -122,7 +127,6 @@ Basic usage expamle:
             # ...
             return Response(status=204)
 
-**.media_type**: `*/*`
 
 ---
 
diff --git a/docs/topics/2.3-announcement.md b/docs/topics/2.3-announcement.md
index 746d3ff7..6677c800 100644
--- a/docs/topics/2.3-announcement.md
+++ b/docs/topics/2.3-announcement.md
@@ -187,6 +187,10 @@ For example, you might have a field that references it's relationship by a hyper
 
 Usage of the old-style attributes continues to be supported, but will raise a `PendingDeprecationWarning`.
 
+## FileUploadParser
+
+2.3 adds a `FileUploadParser` parser class, that supports raw file uploads, in addition to the existing multipart upload support.
+
 ## DecimalField
 
 2.3 introduces a `DecimalField` serializer field, which returns `Decimal` instances.
diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md
index 1081ea4f..d77bebb0 100644
--- a/docs/topics/release-notes.md
+++ b/docs/topics/release-notes.md
@@ -47,6 +47,7 @@ You can determine your currently installed version using `pip freeze`:
 * HyperLinkedModelSerializers support 'id' field in 'fields' option.
 * Cleaner generic views.
 * Support for multiple filter classes.
+* FileUploadParser support for raw file uploads.
 * DecimalField support.
 * Bugfix: Fix issue with depth>1 on ModelSerializer.