diff --git a/docs/source/using_traitlets.rst b/docs/source/using_traitlets.rst
index 967b3680..8263cb4a 100644
--- a/docs/source/using_traitlets.rst
+++ b/docs/source/using_traitlets.rst
@@ -120,6 +120,13 @@ Basic Example: Validating the Parity of a Trait
         parity_check.value = 1
         parity_check.parity = 1
 
+Notice how all of the examples above return
+``proposal['value']``. This is necessary for validation to work
+properly, since the new value of the trait will be the
+return value of the function decorated by ``@validate``. If this
+function does not have any ``return`` statement, then the returned
+value will be ``None``, instead of what we wanted (which is ``proposal['value']``).
+
 However, we recommend that custom cross-validators don't modify the state of
 the HasTraits instance.