Updating fields docs

1 files changed, 166 insertions, 88 deletions

diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md
index 68cdc622..17a65ab8 100644
--- a/docs/api-guide/fields.md
+++ b/docs/api-guide/fields.md
@@ -47,7 +47,7 @@ Defaults to `True`.
 
 ### `allow_null`
 
-Normally an error will be raise if `None` is passed to a serializer field. Set this keyword argument to `True` if `None` should be considered a valid value.
+Normally an error will be raised if `None` is passed to a serializer field. Set this keyword argument to `True` if `None` should be considered a valid value.
 
 Defaults to `False`
 
@@ -100,10 +100,6 @@ Two options are currently used in HTML form generation, `'input_type'` and `'bas
 
 ---
 
-# Generic Fields
-
-These generic fields are used for representing arbitrary model fields or the output of model methods.
-
 ## Field
 
 A generic, **read-only** field.  You can use this field for any attribute that does not need to support write operations.
@@ -146,96 +142,143 @@ By default, the `Field` class will perform a basic translation of the source val
 
 You can customize this  behavior by overriding the `.to_native(self, value)` method.
 
-## WritableField
+**TODO**: Note removal of `WritableField`
 
-A field that supports both read and write operations.  By itself `WritableField` does not perform any translation of input values into a given type.  You won't typically use this field directly, but you may want to override it and implement the `.to_native(self, value)` and `.from_native(self, value)` methods.
+---
 
-## ModelField
+# Boolean fields
 
-A generic field that can be tied to any arbitrary model field.  The `ModelField` class delegates the task of serialization/deserialization to its associated model field.  This field can be used to create serializer fields for custom model fields, without having to create a new custom serializer field.
+## BooleanField
 
-The `ModelField` class is generally intended for internal use, but can be used by your API if needed.  In order to properly instantiate a `ModelField`, it must be passed a field that is attached to an instantiated model.  For example: `ModelField(model_field=MyModel()._meta.get_field('custom_field'))`
+A boolean representation.
 
-**Signature:** `ModelField(model_field=<Django ModelField instance>)`
+Corresponds to `django.db.models.fields.BooleanField`.
 
-## SerializerMethodField
+## NullBooleanField
 
-This is a read-only field.  It gets its value by calling a method on the serializer class it is attached to.  It can be used to add any sort of data to the serialized representation of your object.  The field's constructor accepts a single argument, which is the name of the method on the serializer to be called.  The method should accept a single argument (in addition to `self`), which is the object being serialized.  It should return whatever you want to be included in the serialized representation of the object.  For example:
+A boolean representation that also accepts `None` as a valid value.
 
-    from django.contrib.auth.models import User
-    from django.utils.timezone import now
-    from rest_framework import serializers
+Corresponds to `django.db.models.fields.NullBooleanField`.
 
-    class UserSerializer(serializers.ModelSerializer):
-        days_since_joined = serializers.SerializerMethodField('get_days_since_joined')
+---
 
-        class Meta:
-            model = User
+# String fields
 
-        def get_days_since_joined(self, obj):
-            return (now() - obj.date_joined).days
+## CharField
 
----
+A text representation. Optionally validates the text to be shorter than `max_length` and longer than `min_length`.
 
-# Typed Fields
+Corresponds to `django.db.models.fields.CharField` or `django.db.models.fields.TextField`.
 
-These fields represent basic datatypes, and support both reading and writing values.
+**Signature:** `CharField(max_length=None, min_length=None, allow_none=False)`
 
-## BooleanField
+## EmailField
 
-A Boolean representation.
+A text representation, validates the text to be a valid e-mail address.
 
-Corresponds to `django.db.models.fields.BooleanField`.
+Corresponds to `django.db.models.fields.EmailField`
 
-## CharField
+**Signature:** `EmailField(max_length=None, min_length=None)`
 
-A text representation, optionally validates the text to be shorter than `max_length` and longer than `min_length`.
-If `allow_none` is `False` (default), `None` values will be converted to an empty string.
+## RegexField
 
-Corresponds to `django.db.models.fields.CharField`
-or `django.db.models.fields.TextField`.
+A text representation, that validates the given value matches against a certain regular expression.
 
-**Signature:** `CharField(max_length=None, min_length=None, allow_none=False)`
+The mandatory `regex` argument may either be a string, or a compiled python regular expression object.
 
-## URLField
+Uses Django's `django.core.validators.RegexValidator` for validation.
 
-Corresponds to `django.db.models.fields.URLField`.  Uses Django's `django.core.validators.URLValidator` for validation.
+Corresponds to `django.forms.fields.RegexField`
 
-**Signature:** `URLField(max_length=200, min_length=None)`
+**Signature:** `RegexField(regex, max_length=None, min_length=None)`
 
 ## SlugField
 
+A `RegexField` that validates the input against the pattern `[a-zA-Z0-9_-]+`.
+
 Corresponds to `django.db.models.fields.SlugField`.
 
 **Signature:** `SlugField(max_length=50, min_length=None)`
 
-## ChoiceField
+## URLField
 
-A field that can accept a value out of a limited set of choices. Optionally takes a `blank_display_value` parameter that customizes the display value of an empty choice.
+A `RegexField` that validates the input against a URL matching pattern. Expects fully qualified URLs of the form `http://<host>/<path>`.
 
-**Signature:** `ChoiceField(choices=(), blank_display_value=None)`
+Corresponds to `django.db.models.fields.URLField`.  Uses Django's `django.core.validators.URLValidator` for validation.
 
-## EmailField
+**Signature:** `URLField(max_length=200, min_length=None)`
 
-A text representation, validates the text to be a valid e-mail address.
+---
 
-Corresponds to `django.db.models.fields.EmailField`
+# Numeric fields
 
-## RegexField
+## IntegerField
 
-A text representation, that validates the given value matches against a certain regular expression.
+An integer representation.
 
-Uses Django's `django.core.validators.RegexValidator` for validation.
+Has two optional arguments:
 
-Corresponds to `django.forms.fields.RegexField`
+- `max_value` Validate that the number provided is no greater than this value.
 
-**Signature:** `RegexField(regex, max_length=None, min_length=None)`
+- `min_value` Validate that the number provided is no less than this value.
+
+Corresponds to `django.db.models.fields.IntegerField`, `django.db.models.fields.SmallIntegerField`, `django.db.models.fields.PositiveIntegerField` and `django.db.models.fields.PositiveSmallIntegerField`.
+
+## FloatField
+
+A floating point representation.
+
+Has two optional arguments:
+
+- `max_value` Validate that the number provided is no greater than this value.
+
+- `min_value` Validate that the number provided is no less than this value.
+
+Corresponds to `django.db.models.fields.FloatField`.
+
+## DecimalField
+
+A decimal representation, represented in Python by a Decimal instance.
+
+Has two required arguments, and three optional arguments:
+
+- `max_digits` The maximum number of digits allowed in the number. Note that this number must be greater than or equal to decimal_places.
+
+- `decimal_places` The number of decimal places to store with the number.
+
+- `coerce_to_string` Set to `True` if string values should be returned for the representation, or `False` if `Decimal` objects should be returned. Defaults to the same value as the `COERCE_DECIMAL_TO_STRING` settings key, which will be `True` unless overridden. If `Decimal` objects are returned by the serializer, then the final output format will be determined by the renderer.
+
+- `max_value` Validate that the number provided is no greater than this value.
+
+- `min_value` Validate that the number provided is no less than this value.
+
+#### Example usage
+
+To validate numbers up to 999 with a resolution of 2 decimal places, you would use:
+
+    serializers.DecimalField(max_digits=5, decimal_places=2)
+
+And to validate numbers up to anything less than one billion with a resolution of 10 decimal places:
+
+    serializers.DecimalField(max_digits=19, decimal_places=10)
+
+This field also takes an optional argument, `coerce_to_string`. If set to `True` the representation will be output as a string. If set to `False` the representation will be left as a `Decimal` instance and the final representation will be determined by the renderer.
+
+If unset, this will default to the same value as the `COERCE_DECIMAL_TO_STRING` setting, which is `True` unless set otherwise.
+
+**Signature:** `DecimalField(max_digits, decimal_places, coerce_to_string=None)`
+
+Corresponds to `django.db.models.fields.DecimalField`.
+
+---
+
+# Date and time fields
 
 ## DateTimeField
 
 A date and time representation.
 
-Corresponds to `django.db.models.fields.DateTimeField`
+Corresponds to `django.db.models.fields.DateTimeField`.
 
 When using `ModelSerializer` or `HyperlinkedModelSerializer`, note that any model fields with `auto_now=True` or `auto_now_add=True` will use serializer fields that are `read_only=True` by default.
 
@@ -253,10 +296,10 @@ In the case of JSON this means the default datetime representation uses the [ECM
 
 **Signature:** `DateTimeField(format=None, input_formats=None)`
 
-* `format` - A string representing the output format.  If not specified, this defaults to `None`, which indicates that Python `datetime` objects should be returned by `to_native`.  In this case the datetime encoding will be determined by the renderer.
+* `format` - A string representing the output format.  If not specified, this defaults to the same value as the `DATETIME_FORMAT` settings key, which will be `'iso-8601'` unless set. Setting to a format string indicates that `to_representation` return values should be coerced to string output. Format strings are described below. Setting this value to `None` indicates that Python `datetime` objects should be returned by `to_representation`. In this case the datetime encoding will be determined by the renderer.
 * `input_formats` - A list of strings representing the input formats which may be used to parse the date.  If not specified, the `DATETIME_INPUT_FORMATS` setting will be used, which defaults to `['iso-8601']`.
 
-DateTime format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style datetimes should be used. (eg `'2013-01-29T12:34:56.000000Z'`)
+**DateTimeField format strings**: Format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style datetimes should be used. (eg `'2013-01-29T12:34:56.000000Z'`)
 
 ## DateField
 
@@ -266,63 +309,47 @@ Corresponds to `django.db.models.fields.DateField`
 
 **Signature:** `DateField(format=None, input_formats=None)`
 
-* `format` - A string representing the output format.  If not specified, this defaults to `None`, which indicates that Python `date` objects should be returned by `to_native`.  In this case the date encoding will be determined by the renderer.
+* `format` - A string representing the output format.  If not specified, this defaults to the same value as the `DATE_FORMAT` settings key, which will be `'iso-8601'` unless set. Setting to a format string indicates that `to_representation` return values should be coerced to string output. Format strings are described below. Setting this value to `None` indicates that Python `date` objects should be returned by `to_representation`. In this case the date encoding will be determined by the renderer.
 * `input_formats` - A list of strings representing the input formats which may be used to parse the date.  If not specified, the `DATE_INPUT_FORMATS` setting will be used, which defaults to `['iso-8601']`.
 
-Date format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style dates should be used. (eg `'2013-01-29'`)
+**DateField format strings**: Format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style dates should be used. (eg `'2013-01-29'`)
 
 ## TimeField
 
 A time representation.
 
-Optionally takes `format` as parameter to replace the matching pattern.
-
 Corresponds to `django.db.models.fields.TimeField`
 
 **Signature:** `TimeField(format=None, input_formats=None)`
 
-* `format` - A string representing the output format.  If not specified, this defaults to `None`, which indicates that Python `time` objects should be returned by `to_native`.  In this case the time encoding will be determined by the renderer.
+* `format` - A string representing the output format.  If not specified, this defaults to the same value as the `TIME_FORMAT` settings key, which will be `'iso-8601'` unless set. Setting to a format string indicates that `to_representation` return values should be coerced to string output. Format strings are described below. Setting this value to `None` indicates that Python `time` objects should be returned by `to_representation`. In this case the time encoding will be determined by the renderer.
 * `input_formats` - A list of strings representing the input formats which may be used to parse the date.  If not specified, the `TIME_INPUT_FORMATS` setting will be used, which defaults to `['iso-8601']`.
 
-Time format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style times should be used. (eg `'12:34:56.000000'`)
-
-## IntegerField
-
-An integer representation.
-
-Corresponds to `django.db.models.fields.IntegerField`, `django.db.models.fields.SmallIntegerField`, `django.db.models.fields.PositiveIntegerField` and `django.db.models.fields.PositiveSmallIntegerField`
+**TimeField format strings**: Format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style times should be used. (eg `'12:34:56.000000'`)
 
-## FloatField
-
-A floating point representation.
-
-Corresponds to `django.db.models.fields.FloatField`.
+---
 
-## DecimalField
+# Choice selection fields
 
-A decimal representation, represented in Python by a Decimal instance.
-
-Has two required arguments:
+## ChoiceField
 
-- `max_digits` The maximum number of digits allowed in the number. Note that this number must be greater than or equal to decimal_places.
+A field that can accept a value out of a limited set of choices. Takes a single mandatory argument.
 
-- `decimal_places` The number of decimal places to store with the number.
+- `choices` - A list of valid values, or a list of `(key, display_name)` tuples.
 
-For example, to validate numbers up to 999 with a resolution of 2 decimal places, you would use:
+**Signature:** `ChoiceField(choices=())`
 
-    serializers.DecimalField(max_digits=5, decimal_places=2)
+## MultipleChoiceField
 
-And to validate numbers up to anything less than one billion with a resolution of 10 decimal places:
+A field that can accept a set of zero, one or many values, chosen from a limited set of choices. Takes a single mandatory argument. `to_internal_representation` returns a `set` containing the selected values.
 
-    serializers.DecimalField(max_digits=19, decimal_places=10)
+- `choices` - A list of valid values, or a list of `(key, display_name)` tuples.
 
-This field also takes an optional argument, `coerce_to_string`. If set to `True` the representation will be output as a string. If set to `False` the representation will be left as a `Decimal` instance and the final representation will be determined by the renderer.
+**Signature:** `MultipleChoiceField(choices=())`
 
-If unset, this will default to the same value as the `COERCE_DECIMAL_TO_STRING` setting, which is `True` unless set otherwise.
+---
 
-**Signature:** `DecimalField(max_digits, decimal_places, coerce_to_string=None)`
-
-Corresponds to `django.db.models.fields.DecimalField`.
+# File upload fields
 
 ## FileField
 
@@ -330,15 +357,17 @@ A file representation.  Performs Django's standard FileField validation.
 
 Corresponds to `django.forms.fields.FileField`.
 
-**Signature:** `FileField(max_length=None, allow_empty_file=False)`
+**Signature:** `FileField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)`
+
+ - `max_length` - designates the maximum length for the file name.
 
- - `max_length` designates the maximum length for the file name.
+ - `allow_empty_file` - designates if empty files are allowed.
 
- - `allow_empty_file` designates if empty files are allowed.
+- `use_url` - If set to `True` then URL string values will be used for the output representation. If set to `False` then filename string values will be used for the output representation. Defaults to the value of the `UPLOADED_FILES_USE_URL` settings key, which is `True` unless set otherwise.
 
 ## ImageField
 
-An image representation.
+An image representation. Validates the uploaded file content as matching a known image format.
 
 Corresponds to `django.forms.fields.ImageField`.
 
@@ -348,11 +377,60 @@ Signature and validation is the same as with `FileField`.
 
 ---
 
-**Note:** `FileFields` and `ImageFields` are only suitable for use with MultiPartParser, since e.g. json doesn't support file uploads.
+**Note:** `FileFields` and `ImageFields` are only suitable for use with `MultiPartParser` or `FileUploadParser`. Most parsers, such as e.g. JSON don't support file uploads.
 Django's regular [FILE_UPLOAD_HANDLERS] are used for handling uploaded files.
 
 ---
 
+# Composite fields
+
+## ListField
+
+**TODO**
+
+---
+
+# Miscellaneous fields
+
+## ReadOnlyField
+
+**TODO**
+
+## HiddenField
+
+**TODO**
+
+## ModelField
+
+A generic field that can be tied to any arbitrary model field.  The `ModelField` class delegates the task of serialization/deserialization to its associated model field.  This field can be used to create serializer fields for custom model fields, without having to create a new custom serializer field.
+
+The `ModelField` class is generally intended for internal use, but can be used by your API if needed.  In order to properly instantiate a `ModelField`, it must be passed a field that is attached to an instantiated model.  For example: `ModelField(model_field=MyModel()._meta.get_field('custom_field'))`
+
+**Signature:** `ModelField(model_field=<Django ModelField instance>)`
+
+## SerializerMethodField
+
+This is a read-only field. It gets its value by calling a method on the serializer class it is attached to. It can be used to add any sort of data to the serialized representation of your object.
+
+The field constructor accepts a single optional argument, which is the name of the method on the serializer to be called. If not included this defaults to `get_<field_name>`.
+
+The method should accept a single argument (in addition to `self`), which is the object being serialized.  It should return whatever you want to be included in the serialized representation of the object.  For example:
+
+    from django.contrib.auth.models import User
+    from django.utils.timezone import now
+    from rest_framework import serializers
+
+    class UserSerializer(serializers.ModelSerializer):
+        days_since_joined = serializers.SerializerMethodField()
+
+        class Meta:
+            model = User
+
+        def get_days_since_joined(self, obj):
+            return (now() - obj.date_joined).days
+
+---
+
 # Custom fields
 
 If you want to create a custom field, you'll probably want to override either one or both of the `.to_native()` and `.from_native()` methods.  These two methods are used to convert between the initial datatype, and a primitive, serializable datatype.  Primitive datatypes may be any of a number, string, date/time/datetime or None.  They may also be any list or dictionary like object that only contains other primitive objects.