[1.7.x] Fixed #22786 -- Documented value_from_datadict caveat

Thanks blueyed for the report and Tim Graham for the review.
Backport of 909015a51b from master.

1 files changed, 6 insertions, 1 deletions

diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt
index e5963397a2..45f5d83887 100644
--- a/docs/ref/forms/widgets.txt
+++ b/docs/ref/forms/widgets.txt
@@ -217,7 +217,12 @@ foundation for custom widgets.
     .. method:: value_from_datadict(data, files, name)
 
         Given a dictionary of data and this widget's name, returns the value
-        of this widget. Returns ``None`` if a value wasn't provided.
+        of this widget. ``files`` may contain data coming from
+        :attr:`request.FILES <django.http.HttpRequest.FILES>`. Returns ``None``
+        if a value wasn't provided. Note also that ``value_from_datadict`` may
+        be called more than once during handling of form data, so if you
+        customize it and add expensive processing, you should implement some
+        caching mechanism yourself.
 
 .. class:: MultiWidget(widgets, attrs=None)