[Numpy-discussion] Re: Vote: complex64 vs complex128

[Arnd Baecker]

Hi,

On Wed, 5 Apr 2006, Tim Hochberg wrote:

[...]

> That's right, none of the scalar types have docstrings at present. The
> builtin help (AKA pydoc.help) tracks back through all the base classes
> and presents all kinds of extra information.

I see - so that might be something Ipython could do as well
(if that's really what we would like to see...)

> The result tends to be
> awfully verbose; so much so that I just stuffed a function called hint
> into __builtins___ that just prints the results of pydoc.describe and
> pydoc.getdoc. It's quite possible that such a function already exists,
> maybe even in pydoc, but oddly enough the docs for pydoc are pretty
> impenatrable.
>
> Here I've added basic docstrings to the complex types. I was hoping
> someone would have some ideas for other stuff that should go into the
> docstrings, but perhaps I'll just commit that change as is. Here's what
> I see here using hint:
>
>  >>> hint(numpy.float64) # Still no docstring
> class float64scalar
>  >>> hint(numpy.complex64) # Now has a terse docstring
> class complex64scalar
>  |  Composed of two 32 bit floats
>  >>> hint(numpy.complex128) # Same here.
> class complex128scalar
>  |  Composed of two 64 bit floats

That looks much better.
I am a bit unsure about `hint` though for the following reasons:
There are quite a few ways  to access documentation:
  - help(defined_object)
  - help("numpy.complex128")
  - scipy.info(defined_object)
  - hint(defined_object)
  - defined_object?                     # with IPython
(and then of course the pydoc commands as well ...).

Clearly, I would prefer to have "?" in IPython as the only thing one needs
to know about accessing documentation.

There are surely many aspects to consider here, but I have to rush now ...

Best, Arnd