[docs] [issue25777] Misleading descriptions in docs about invoking descriptors.

[Juchen Zeng]

New submission from Juchen Zeng:

[Doc Link](https://docs.python.org/2/howto/descriptor.html#invoking-descriptors)

In descriptions about how to invoke descriptors with super(), it says:

    The call super(B, obj).m() searches obj.__class__.__mro__ for the base class A immediately following B and then returns A.__dict__['m'].__get__(obj, B). If not a descriptor, m is returned unchanged. If not in the dictionary, m reverts to a search using object.__getattribute__().

But the call ` super(B, obj).m()` will not return `A.__dict__['m'].__get__(obj, B)`, it will trigger the `__call__` method of ` A.__dict__['m'].__get__(obj, B)` if it has that attr, and return what this `__call__` method returns.  It could be anything.
It's actually `super(B, obj).m` returns `A.__dict__['m'].__get__(obj, B)` if m is a descriptor.

In short, the original description in the doc can be abbreviated to:
`The call super(B, obj).m() [did something] and returns A.__dict__['m'].__get__(obj, B).`
Which is obviously misleading.

As the method/function call isn't the core part in this sentence. I suggest the doc to be fixed like this:

    The action super(B, obj).m searches obj.__class__.__mro__ for the base class A immediately following B and then returns A.__dict__['m'].__get__(obj, B).

----------
assignee: docs at python
components: Documentation
messages: 255712
nosy: Juchen Zeng, docs at python, martin.panter
priority: normal
severity: normal
status: open
title: Misleading descriptions in docs about invoking descriptors.
versions: Python 2.7

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