2 files changed, 33 insertions, 8 deletions
diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index 8a5303710a..950bd3a088 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -652,8 +652,13 @@ Note that the label suffix is added only if the last character of the
 label isn't a punctuation character (in English, those are ``.``, ``!``, ``?``
 or ``:``).
 
-You can also customize the ``label_suffix`` on a per-field basis using the
-``label_suffix`` parameter to :meth:`~django.forms.BoundField.label_tag`.
+.. versionadded:: 1.8
+
+Fields can also define their own :attr:`~django.forms.Field.label_suffix`.
+This will take precedence over :attr:`Form.label_suffix
+<django.forms.Form.label_suffix>`. The suffix can also be overridden at runtime
+using the ``label_suffix`` parameter to
+:meth:`~django.forms.BoundField.label_tag`.
 
 Notes on field ordering
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -799,12 +804,12 @@ auto-generated label tag. An optional ``attrs`` dictionary may contain
 additional attributes for the ``<label>`` tag.
 
 The HTML that's generated includes the form's
-:attr:`~django.forms.Form.label_suffix` (a colon, by default). The optional
-``label_suffix`` parameter allows you to override the form's
-:attr:`~django.forms.Form.label_suffix`. For example, you can use an empty
-string to hide the label on selected fields. If you need to do this in a
-template, you could write a custom filter to allow passing parameters to
-``label_tag``.
+:attr:`~django.forms.Form.label_suffix` (a colon, by default) or, if set, the
+current field's :attr:`~django.forms.Field.label_suffix`. The optional
+``label_suffix`` parameter allows you to override any previously set
+suffix. For example, you can use an empty string to hide the label on selected
+fields. If you need to do this in a template, you could write a custom
+filter to allow passing parameters to ``label_tag``.
 
 .. versionchanged:: 1.8
 
diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index ec9ea3a85e..e9d877b222 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -119,6 +119,26 @@ We've specified ``auto_id=False`` to simplify the output::
     <tr><th>Your Web site:</th><td><input type="url" name="url" /></td></tr>
     <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
 
+``label_suffix``
+~~~~~~~~~~~~~~~~
+
+.. attribute:: Field.label_suffix
+
+.. versionadded:: 1.8
+
+The ``label_suffix`` argument lets you override the form's
+:attr:`~django.forms.Form.label_suffix` on a per-field basis::
+
+    >>> class ContactForm(forms.Form):
+    ...     age = forms.IntegerField()
+    ...     nationality = forms.CharField()
+    ...     captcha_answer = forms.IntegerField(label='2 + 2', label_suffix=' =')
+    >>> f = ContactForm(label_suffix='?')
+    >>> print(f.as_p())
+    <p><label for="id_age">Age?</label> <input id="id_age" name="age" type="number" /></p>
+    <p><label for="id_nationality">Nationality?</label> <input id="id_nationality" name="nationality" type="text" /></p>
+    <p><label for="id_captcha_answer">2 + 2 =</label> <input id="id_captcha_answer" name="captcha_answer" type="number" /></p>
+
 ``initial``
 ~~~~~~~~~~~