Merge branch 'master' into writable-nested-modelserializer

1 files changed, 7 insertions, 5 deletions

diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md
index 44ee7e39..d9c23580 100644
--- a/docs/api-guide/serializers.md
+++ b/docs/api-guide/serializers.md
@@ -8,7 +8,7 @@ will take some serious design work.
 >
 > — Russell Keith-Magee, [Django users group][cite]
 
-Serializers allow complex data such as querysets and model instances to be converted to native python datatypes that can then be easily rendered into `JSON`, `XML` or other content types.  Serializers also provide deserialization, allowing parsed data to be converted back into complex types, after first validating the incoming data.
+Serializers allow complex data such as querysets and model instances to be converted to native Python datatypes that can then be easily rendered into `JSON`, `XML` or other content types.  Serializers also provide deserialization, allowing parsed data to be converted back into complex types, after first validating the incoming data.
 
 REST framework's serializers work very similarly to Django's `Form` and `ModelForm` classes.  It provides a `Serializer` class which gives you a powerful, generic way to control the output of your responses, as well as a `ModelSerializer` class which provides a useful shortcut for creating serializers that deal with model instances and querysets.
 
@@ -39,7 +39,7 @@ Declaring a serializer looks very similar to declaring a form:
             an existing model instance, or create a new model instance.
             """
             if instance is not None:
-                instance.title = attrs.get('title', instance.title)
+                instance.email = attrs.get('email', instance.email)
                 instance.content = attrs.get('content', instance.content)
                 instance.created = attrs.get('created', instance.created)
                 return instance
@@ -57,7 +57,7 @@ We can now use `CommentSerializer` to serialize a comment, or list of comments.
     serializer.data
     # {'email': u'leila@example.com', 'content': u'foo bar', 'created': datetime.datetime(2012, 8, 22, 16, 20, 9, 822774)}
 
-At this point we've translated the model instance into python native datatypes.  To finalise the serialization process we render the data into `json`.
+At this point we've translated the model instance into Python native datatypes.  To finalise the serialization process we render the data into `json`.
 
     json = JSONRenderer().render(serializer.data)
     json
@@ -65,7 +65,7 @@ At this point we've translated the model instance into python native datatypes.
 
 ## Deserializing objects
         
-Deserialization is similar.  First we parse a stream into python native datatypes... 
+Deserialization is similar.  First we parse a stream into Python native datatypes... 
 
     stream = StringIO(json)
     data = JSONParser().parse(stream)
@@ -387,7 +387,7 @@ There needs to be a way of determining which views should be used for hyperlinki
 
 By default hyperlinks are expected to correspond to a view name that matches the style `'{model_name}-detail'`, and looks up the instance by a `pk` keyword argument.
 
-You can change the field that is used for object lookups by setting the `lookup_field` option.  The value of this option should correspond both with a kwarg in the URL conf, and with an field on the model.  For example:
+You can change the field that is used for object lookups by setting the `lookup_field` option.  The value of this option should correspond both with a kwarg in the URL conf, and with a field on the model.  For example:
 
     class AccountSerializer(serializers.HyperlinkedModelSerializer):
         class Meta:
@@ -395,6 +395,8 @@ You can change the field that is used for object lookups by setting the `lookup_
             fields = ('url', 'account_name', 'users', 'created')
             lookup_field = 'slug'
 
+Not that the `lookup_field` will be used as the default on *all* hyperlinked fields, including both the URL identity, and any hyperlinked relationships.
+
 For more specfic requirements such as specifying a different lookup for each field, you'll want to set the fields on the serializer explicitly.  For example:
 
     class AccountSerializer(serializers.HyperlinkedModelSerializer):