[docs] [issue22174] property doc fixes

[diana]

diana added the comment:

This whitespace? Or did you mean something else?

      class C:
          def __init__(self):
              self._x = None

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

versus:

      class C:
          def __init__(self):
              self._x = None

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

I added it to be consistent with the rest of the code snippets in the property docs. For example:

      class C:
          def __init__(self):
              self._x = None

          @property
          def x(self):
              """I'm the 'x' property."""
              return self._x

          @x.setter
          def x(self, value):
              self._x = value

          @x.deleter
          def x(self):
              del self._x

Of the three code snippets in the property docs, that first one is the only one that doesn't have whitespace between the methods. That first code snippet also has inconsistent whitespace within itself (__init__ vs the rest of methods).

Anyhoo, that was my reasoning, but that's largely beside the point. I will happily drop it and leave it as-is. What really prompted me to submit a patch was this paragraph:

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

I now understand the original intent, but I don't think it's clear as-is. 

I also find it a bit odd that 'fget', 'fset', 'fdel' are all defined in the first sentence of the docs, but 'doc' isn't. It then launches into an example that uses 'doc' (still as of yet undefined), before defining 'doc' later on in the read-only properties part.

I'll think on it a bit some more -- feel free to close this in the mean time. It's been this way for a better part of a decade, so perhaps it's just me ;)

Cheers,

--diana

----------

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