[Python-checkins] cpython (2.7): Issue #22174: Clean-up grammar and ambiguities in property() docs.

[raymond.hettinger]

http://hg.python.org/cpython/rev/98a2e215ff01
changeset:   92066:98a2e215ff01
branch:      2.7
parent:      92061:4331fa01398e
user:        Raymond Hettinger <python at rcn.com>
date:        Sun Aug 10 10:44:21 2014 -0700
summary:
  Issue #22174:  Clean-up grammar and ambiguities in property() docs.

files:
  Doc/library/functions.rst |  20 +++++++++++++-------
  Misc/ACKS                 |   1 +
  2 files changed, 14 insertions(+), 7 deletions(-)


diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
--- 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
diff --git a/Misc/ACKS b/Misc/ACKS
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -245,6 +245,7 @@
 Craig Citro
 Gilles Civario
 Chris Clark
+Diana Clarke
 Laurie Clark-Michalek
 Mike Clarkson
 Andrew Clegg

-- 
Repository URL: http://hg.python.org/cpython