diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index e7b98eb44b2e21..3f84aeda9c8f9d 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1388,6 +1388,17 @@ are always available.  They are listed here in alphabetical order.
    object allows it.  For example, ``setattr(x, 'foobar', 123)`` is equivalent to
    ``x.foobar = 123``.
 
+.. note::
+
+   setattr() attempts to update the object with the given attr/value pair.
+   Whether this succeeds and the effect it has determined by the target object.
+   If an object's class defines `__slots__`, the attribute may not be writeable.
+   If an object's class defines :class:`property` with a setter method, the *setattr()*
+   will trigger the setter method which may or may not actually write the attribute.
+   For objects that have a regular dictionary (which is the typical case), the
+   *setattr()* call can make any string keyed update allowed by the dictionary
+   including keys that aren't valid identifiers -- for example ``setattr(a, '1', 'one')``
+   will be the equivalent of ``vars()['1'] ='one'``.
 
 .. class:: slice(stop)
            slice(start, stop[, step])