--- functions.rst	2016-12-02 11:10:45.534696497 +0100
+++ functions_new.rst	2016-12-02 12:28:30.574772125 +0100
@@ -777,8 +777,19 @@
 .. function:: locals()
 
    Update and return a dictionary representing the current local symbol table.
-   Free variables are returned by :func:`locals` when it is called in function
-   blocks, but not in class blocks.
+   Free variables belonging to the enclosing local namespaces are also
+   returned by :func:`locals`::
+
+      >>> def foo():
+      ...     a = 20
+      ...     def moo():
+      ...         c = a + 1
+      ...         print(locals())
+      ...     return moo
+      ... 
+      >>> moo = foo()
+      >>> moo()
+      {'a': 20, 'c': 21}
 
    .. note::
       The contents of this dictionary should not be modified; changes may not