Fixed #21654 -- Documented a use-case for Form.errors.as_data().

Thanks selwin for the suggestion.

2 files changed, 21 insertions, 0 deletions

diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index 7f2de3fa03..5a9f6a1cdc 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -128,6 +128,20 @@ instances.
     {'sender': [ValidationError(['Enter a valid email address.'])],
     'subject': [ValidationError(['This field is required.'])]}
 
+Use this method anytime you need to identify an error by its ``code``. This
+enables things like rewriting the error's message or writing custom logic in a
+view when a given error is present. It can also be used to serialize the errors
+in a custom format (e.g. XML); for instance, :meth:`~Form.errors.as_json()`
+relies on ``as_data()``.
+
+The need for the ``as_data()`` method is due to backwards compatibility.
+Previously ``ValidationError`` instances were lost as soon as their
+**rendered** error messages were added to the ``Form.errors`` dictionary.
+Ideally ``Form.errors`` would have stored ``ValidationError`` instances
+and methods with an ``as_`` prefix could render them, but it had to be done
+the other way around in order not to break code that expects rendered error
+messages in ``Form.errors``.
+
 .. method:: Form.errors.as_json()
 
 .. versionadded:: 1.7
diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt
index 569e7e77e7..78a022d436 100644
--- a/docs/ref/forms/validation.txt
+++ b/docs/ref/forms/validation.txt
@@ -179,6 +179,13 @@ to override your error message you can still opt for the less verbose::
 
     ValidationError(_('Invalid value: %s') % value)
 
+.. versionadded:: 1.7
+
+The :meth:`Form.errors.as_data() <django.forms.Form.errors.as_data()>` and
+:meth:`Form.errors.as_json() <django.forms.Form.errors.as_json()>` methods
+greatly benefit from fully featured ``ValidationError``\s (with a ``code`` name
+and a ``params`` dictionary).
+
 Raising multiple errors
 ~~~~~~~~~~~~~~~~~~~~~~~