diff -r 748fb6d622e8 Doc/library/functions.rst
--- a/Doc/library/functions.rst	Fri Aug 08 13:35:11 2014 -0500
+++ b/Doc/library/functions.rst	Fri Aug 08 16:44:36 2014 -0400
@@ -1107,8 +1107,11 @@
    Return a property attribute.
 
    *fget* is a function for getting an attribute value, likewise *fset* is a
-   function for setting, and *fdel* a function for del'ing, an attribute.  Typical
-   use is to define a managed attribute ``x``::
+   function for setting, and *fdel* a function for del'ing an attribute. If
+   given, *doc* will be the docstring of the property attribute. Otherwise,
+   the property will copy *fget*'s docstring (if it exists).
+
+   Typical use is to define a managed attribute ``x``::
 
       class C:
           def __init__(self):
@@ -1116,18 +1119,20 @@
 
           def getx(self):
               return self._x
+
           def setx(self, value):
               self._x = value
+
           def delx(self):
               del self._x
+
           x = property(getx, setx, delx, "I'm the 'x' property.")
 
-   If then *c* is an instance of *C*, ``c.x`` will invoke the getter,
+   If *c* is an instance of *C*, ``c.x`` will invoke the getter,
    ``c.x = value`` will invoke the setter and ``del c.x`` the deleter.
 
-   If given, *doc* will be the docstring of the property attribute. Otherwise, the
-   property will copy *fget*'s docstring (if it exists).  This makes it possible to
-   create read-only properties easily using :func:`property` as a :term:`decorator`::
+   This makes it possible to create read-only properties easily using
+   :func:`property` as a :term:`decorator`::
 
       class Parrot:
           def __init__(self):
@@ -1138,8 +1143,12 @@
               """Get the current voltage."""
               return self._voltage
 
-   turns the :meth:`voltage` method into a "getter" for a read-only attribute
-   with the same name.
+   The ``@property`` decorator turns the :meth:`voltage` method into a
+   "getter" for a read-only attribute with the same name.
+
+      >>> p = Parrot()
+      >>> p.voltage
+      100000
 
    A property object has :attr:`~property.getter`, :attr:`~property.setter`,
    and :attr:`~property.deleter` methods usable as decorators that create a