Clarifications to read_only fields. Closes #3064.

docs/api-guide/fields.md

@@ -20,6 +20,8 @@ Each serializer field class constructor takes at least these arguments.  Some Fi
 
 ### `read_only`
 
+Read-only fields are included in the API output, but should not be included in the input during create or update operations. Any 'read_only' fields that are incorrectly included in the serializer input will be ignored. 
+
 Set this to `True` to ensure that the field is used when serializing a representation, but is not used when creating or updating an instance during deserialization.
 
 Defaults to `False`

rest_framework/serializers.py

@@ -825,6 +825,10 @@ class ModelSerializer(Serializer):
     def update(self, instance, validated_data):
         raise_errors_on_nested_writes('update', self, validated_data)
 
+        # Simply set each attribute on the instance, and then save it.
+        # Note that unlike `.create()` we don't need to treat many-to-many
+        # relationships as being a special case. During updates we already
+        # have an instance pk for the relationships to be associated with.
         for attr, value in validated_data.items():
             setattr(instance, attr, value)
         instance.save()