Issue #22174: Clean-up grammar and ambiguities in property() docs.
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 0667ec5..f2e6b6c 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -992,9 +992,11 @@
Return a property attribute for :term:`new-style class`\es (classes that
derive from :class:`object`).
- *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``::
+ *fget* is a function for getting an attribute value. *fset* is a function
+ for setting an attribute value. *fdel* is a function for deleting an attribute
+ value. And *doc* creates a docstring for the attribute.
+
+ A typical use is to define a managed attribute ``x``::
class C(object):
def __init__(self):
@@ -1002,13 +1004,16 @@
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
@@ -1024,8 +1029,9 @@
"""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, and it sets the docstring for
+ *voltage* to "Get the current voltage."
A property object has :attr:`~property.getter`, :attr:`~property.setter`,
and :attr:`~property.deleter` methods usable as decorators that create a
@@ -1053,7 +1059,7 @@
additional functions the same name as the original property (``x`` in this
case.)
- The returned property also has the attributes ``fget``, ``fset``, and
+ The returned property object also has the attributes ``fget``, ``fset``, and
``fdel`` corresponding to the constructor arguments.
.. versionadded:: 2.2