Extra note on method

2 files changed, 13 insertions, 1 deletions

diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md
index e7e1670b..e8d3c1b5 100644
--- a/docs/api-guide/serializers.md
+++ b/docs/api-guide/serializers.md
@@ -25,6 +25,7 @@ Let's start by creating a simple object we can use for example purposes:
     comment = Comment(email='leila@example.com', content='foo bar')
 
 We'll declare a serializer that we can use to serialize and deserialize `Comment` objects.
+
 Declaring a serializer looks very similar to declaring a form:
 
     class CommentSerializer(serializers.Serializer):
@@ -33,6 +34,13 @@ Declaring a serializer looks very similar to declaring a form:
         created = serializers.DateTimeField()
 
         def restore_object(self, attrs, instance=None):
+            """
+            Given a dictionary of deserialized field values, either update
+            an existing model instance, or create a new model instance.
+            
+            Note that if we don't define this method, then deserializing
+            data will simply return a dictionary of items.
+            """
             if instance is not None:
                 instance.title = attrs['title']
                 instance.content = attrs['content']
diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md
index 6709f751..205ee7e0 100644
--- a/docs/tutorial/1-serialization.md
+++ b/docs/tutorial/1-serialization.md
@@ -126,7 +126,11 @@ The first thing we need to get started on our Web API is provide a way of serial
     
         def restore_object(self, attrs, instance=None):
             """
-            Create or update a new snippet instance.
+            Create or update a new snippet instance, given a dictionary
+            of deserialized field values.
+            
+            Note that if we don't define this method, then deserializing
+            data will simply return a dictionary of items.
             """
             if instance:
                 # Update existing instance