Switch from clean_<fieldname> to validate_<fieldname>, clarify documentation

docs/api-guide/serializers.md

@@ -80,19 +80,21 @@ When deserializing data, you always need to call `is_valid()` before attempting
 
 ## Custom field validation
 
-Like Django forms, you can specify custom field-level validation by adding `clean_<fieldname>()` methods to your `Serializer` subclass. This method takes a dictionary of deserialized data as a first argument, and the field name in that data as a second argument (which will be either the name of the field or the value of the `source` argument, if one was provided.) It should either return the data dictionary or raise a `ValidationError`. For example:
+You can specify custom field-level validation by adding `validate_<fieldname>()` methods to your `Serializer` subclass. These are analagous to `clean_<fieldname>` methods on Django forms, but accept slightly different arguments. They take a dictionary of deserialized data as a first argument, and the field name in that data as a second argument (which will be either the name of the field or the value of the `source` argument to the field, if one was provided). Your `validate_<fieldname>` methods should either just return the data dictionary or raise a `ValidationError`. For example:
 
-    class BlogPostSerializer(Serializer):
+    from rest_framework import serializers
+
+    class BlogPostSerializer(serializers.Serializer):
         title = serializers.CharField(max_length=100)
         content = serializers.CharField()
 
-        def clean_title(self, data, source):
+        def validate_title(self, data, source):
             """
             Check that the blog post is about Django
             """
             value = data[source]
             if "Django" not in value:
-                raise ValidationError("Blog post is not about Django")
+                raise serializers.ValidationError("Blog post is not about Django")
             return data
 
 ## Dealing with nested objects

rest_framework/serializers.py

@@ -210,13 +210,13 @@ class BaseSerializer(Field):
 
     def clean_fields(self, data):
         """
-        Run clean_<fieldname> validators on the serializer
+        Run validate_<fieldname> methods on the serializer
         """
         fields = self.get_fields(serialize=False, data=data, nested=self.opts.nested)
 
         for field_name, field in fields.items():
             try:
-                clean_method = getattr(self, 'clean_%s' % field_name, None)
+                clean_method = getattr(self, 'validate_%s' % field_name, None)
                 if clean_method:
                     source = field.source or field_name
                     data = clean_method(data, source)

rest_framework/tests/serializer.py

@@ -142,7 +142,7 @@ class ValidationTests(TestCase):
 
         class CommentSerializerWithFieldValidator(CommentSerializer):
 
-            def clean_content(self, attrs, source):
+            def validate_content(self, attrs, source):
                 value = attrs[source]
                 if "test" not in value:
                     raise serializers.ValidationError("Test not in value")