[issue40257] Improve the use of __doc__ in pydoc

[Matthias Bussonnier]

Matthias Bussonnier <bussonniermatthias at gmail.com> added the comment:

> can you clarify your example? What's load()? And what does df?? do?

It was vague on purpose, 

`load()` would be for example `load_csv()` from `pandas` that return a `pandas.DataFrame`. The point being that users typically won't really know the type of what they will get, they may get a DataFrame, but they may get a subclass if for example they use `dask` to do distributed computing. 

`?` or `??` is the way to get help in IPython/Jupyter, we try to pull as much information as we can and under the hood call `inspect.getdoc()`.

Assuming 

In [4]: class A:
   ...:     "doc"

In [5]: class B(A):
   ...:     pass

In [6]: b = B()

Python 3.8 gives:

In [9]: b?
Type:            B
String form:     <__main__.B object at 0x104be7d00>
Docstring:       <no docstring>
Class docstring: doc

Python 3.9 give

In [4]: b?
Type:        B
String form: <__main__.B object at 0x10a0b7140>
Docstring:   <no docstring>


We do already pull docs from the superclass of the instance if no doc is found on current object, but now we get even less for the user. We could of course publish patch and walk the hierarchy ourselves, but it will require many users to upgrade (which you of course know they are not good at).

(Here i'm using `?`, `??` try to pull even more informations like the source, known subclasses and other stuff)


(Will try to get examples with actual code, but I haven't had time to build pandas or other scientific package on 3.9 yet).

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue40257>
_______________________________________