Document compound types: DictField, ListField

docs/api-guide/fields.md

@@ -297,6 +297,35 @@ Django's regular [FILE_UPLOAD_HANDLERS] are used for handling uploaded files.
 
 ---
 
+# Compound Fields
+
+These fields represent compound datatypes, which build on other fields with some additional aspect such collecting multiple elements.
+
+## ListField
+
+A list representation, whose elements are described by a given item field. This means that all elements must meet the definition of
+that field. The item field can be another field type (e.g., CharField) or a serializer. If `item_field` is not given, then the
+list-items are passed through as-is, and can be anything. Note that in this case, any non-native list elements wouldn't be properly
+prepared for data rendering.
+
+**Signature:** `ListField(item_field=None)`
+
+## DictField
+
+A dictionary representation, whose values are described by a given value field. This means that all values must meet the definition of
+that field. The value field can be another field type (e.g., CharField) or a serializer. If `value_field` is not given, then the `dict`
+values are passed through-as-is, and can be anything. Note that in this case, any non-native `dict` values wouldn't be properly
+prepared for data rendering.
+
+Dictionary keys are presumed to be character strings or convertible to such, and so during processing are casted to `unicode`. If
+necessary, options for unicode conversion (such as the encoding, or error processing) can be provided to a `DictField`. For more info,
+see [py_unicode].
+
+**Signature:** `DictField(value_field=None, unicode_options=None)`
+
+If given, unicode_options must be a dict providing options per the [unicode](http://docs.python.org/2/library/functions.html#unicode)
+function.
+
 # 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.
@@ -345,3 +374,4 @@ As an example, let's create a field that can be used represent the class name of
 [ecma262]: http://ecma-international.org/ecma-262/5.1/#sec-15.9.1.15
 [strftime]: http://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior
 [iso8601]: http://www.w3.org/TR/NOTE-datetime
+[py_unicode]: http://docs.python.org/2/howto/unicode.html