[IPython-dev] instance docstring vs class docstring

[Gael Varoquaux]

On Thu, May 10, 2007 at 12:11:42AM -0600, Fernando Perez wrote:
> On 5/8/07, Gael Varoquaux <gael.varoquaux at normalesup.org> wrote:

> >Is there a way to avoid this inconvenient ? Do you think modifying
> >ipython's "help" function to workaround this would be a good idea ?

> help() is part of pydoc, which is, how should I say this politely... a
> bit 'messy' :)

> So I'm not sure that monkeypatching help() is such a terrific idea.

>From a software engineering I definitely agree with you. From a user
experience things are not as obvious. But this kind of choice obvious
goes to the maintainers of the software :->.

> I'd rather improve '?' so we show *both* instance and class docstrings
> when available and different, so that users get all the possible info
> about an object (it's likely they both contain useful things).

Sure. I must admit I like "?" the way it is. Actually I just checked and I
think this is the way it is behaving, currently.

The reason I was asing this was for the physical constants module. The
objects docstrings are helpful, most helpful actually. The class
docstrings are also quite helpful, though for beginners the mention of
"__str__" and "__repr__" can be a bit confusing.

Gaël