From 7815811fe3047b5110e6993ecd72349f6f232232 Mon Sep 17 00:00:00 2001
From: Mark Aaron Shirley <maspwr@gmail.com>
Date: Sun, 14 Jul 2013 18:13:37 -0700
Subject: [PATCH 1/2] Update nested serialization docs

---
 docs/api-guide/relations.md   |  2 --
 docs/api-guide/serializers.md | 17 ++++++++++-------
 2 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/docs/api-guide/relations.md b/docs/api-guide/relations.md
index 50c9bc546..21942eeff 100644
--- a/docs/api-guide/relations.md
+++ b/docs/api-guide/relations.md
@@ -213,8 +213,6 @@ Nested relationships can be expressed by using serializers as fields.
 
 If the field is used to represent a to-many relationship, you should add the `many=True` flag to the serializer field.
 
-Note that nested relationships are currently read-only.  For read-write relationships, you should use a flat relational style.
-
 ## Example
 
 For example, the following serializer:
diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md
index d9c23580c..23c999429 100644
--- a/docs/api-guide/serializers.md
+++ b/docs/api-guide/serializers.md
@@ -177,7 +177,7 @@ If a nested representation may optionally accept the `None` value you should pas
         content = serializers.CharField(max_length=200)
         created = serializers.DateTimeField()
 
-Similarly if a nested representation should be a list of items, you should the `many=True` flag to the nested serialized.
+Similarly if a nested representation should be a list of items, you should pass the `many=True` flag to the nested serialized.
 
     class CommentSerializer(serializers.Serializer):
         user = UserSerializer(required=False)
@@ -185,11 +185,13 @@ Similarly if a nested representation should be a list of items, you should the `
         content = serializers.CharField(max_length=200)
         created = serializers.DateTimeField()
 
----
+Validation of nested objects will work the same as before.  Errors with nested objects will be nested under the field name of the nested object.
 
-**Note**: Nested serializers are only suitable for read-only representations, as there are cases where they would have ambiguous or non-obvious behavior if used when updating instances.  For read-write representations you should always use a flat representation, by using one of the `RelatedField` subclasses.
-
----
+    serializer = CommentSerializer(comment, data={'user': {'email': 'foobar', 'user': 'doe'}, 'content': 'baz'})
+    serializer.is_valid()
+    # False
+    serializer.errors
+    # {'user': {'email': [u'Enter a valid e-mail address.']}, 'created': [u'This field is required.']}
 
 ## Dealing with multiple objects
 
@@ -293,8 +295,7 @@ You can provide arbitrary additional context by passing a `context` argument whe
 
 The context dictionary can be used within any serializer field logic, such as a custom `.to_native()` method, by accessing the `self.context` attribute.
 
----
-
+-
 # ModelSerializer
 
 Often you'll want serializer classes that map closely to model definitions.
@@ -331,6 +332,8 @@ The default `ModelSerializer` uses primary keys for relationships, but you can a
 
 The `depth` option should be set to an integer value that indicates the depth of relationships that should be traversed before reverting to a flat representation.
 
+If you want to customize the way the serialization is done (e.g. using `allow_add_remove`) you'll need to define the field yourself.
+
 ## Specifying which fields should be read-only 
 
 You may wish to specify multiple fields as read-only.  Instead of adding each field explicitly with the `read_only=True` attribute, you may use the `read_only_fields` Meta option, like so:

From b5dc6b61131cc36b0540133a28613c06e7f4e26a Mon Sep 17 00:00:00 2001
From: Mark Aaron Shirley <maspwr@gmail.com>
Date: Sun, 14 Jul 2013 18:18:39 -0700
Subject: [PATCH 2/2] Fix docs typo

---
 docs/api-guide/serializers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md
index 23c999429..022853caa 100644
--- a/docs/api-guide/serializers.md
+++ b/docs/api-guide/serializers.md
@@ -187,7 +187,7 @@ Similarly if a nested representation should be a list of items, you should pass
 
 Validation of nested objects will work the same as before.  Errors with nested objects will be nested under the field name of the nested object.
 
-    serializer = CommentSerializer(comment, data={'user': {'email': 'foobar', 'user': 'doe'}, 'content': 'baz'})
+    serializer = CommentSerializer(comment, data={'user': {'email': 'foobar', 'username': 'doe'}, 'content': 'baz'})
     serializer.is_valid()
     # False
     serializer.errors