[New-bugs-announce] [issue22174] property doc fixes

[diana]

New submission from diana:

The property docs are a bit funky.

    https://docs.python.org/3/library/functions.html#property

1) docstrings have zero to do with making a read-only property. It currently says:

"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 property() as a decorator:"

2) The 'then' in this sentence is awkward (and incorrect English).

"If then 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."

3) This sentence is missing a beginning.

"turns the voltage() method into a “getter” for a read-only attribute with the same name."

4) This sentence has an extra comma (after del'ing):

"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."

Attached is a patch with minimal changes to the property docs, addressing the above four issues. Okay, that's not entirely true -- I did add an example usage because the current docs don't actually show using a property attribute.

>>> p = Parrot()
>>> p.voltage
100000

I've also attached an "after" screenshot of the docs in case it helps with review.

Cheers,

--diana

----------
assignee: docs at python
components: Documentation
files: property_docs.patch
keywords: patch
messages: 225086
nosy: diana, docs at python
priority: normal
severity: normal
status: open
title: property doc fixes
versions: Python 3.5
Added file: http://bugs.python.org/file36318/property_docs.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue22174>
_______________________________________