Integers have docstring for int()

[Christian Tismer]

Skip Montanaro wrote:

>     Andrew> I accidentally discovered that all the basic types in Python
>     Andrew> have docstrings that describe the functions to create them. For
>     Andrew> integers, you get:
>     ...
> 
>     Andrew> This seems a little unexpected to me; is there any particular
>     Andrew> reason for this behaviour?
> 
> Why should this be unexpected?  If you execute
> 
>     print int.__doc__
> 
> you get its docstring.  Since the __doc__ attribute is attached to the class
> it will be found when the search starts at an instance of the class as well.

Sure, this is why. But I can understand the feeling a little
bit, because the docstring describes what a __call__ to the
type object does, although the instance is not even callable.

This may origin in the fact, that int and str have been just
functions a short while back, and the docstrings mainly describe
that function call. The docs are less representative
for int being the whole class. One would perhaps expect
a short description of what an int can do.
On the other hand, int() perceived as a function still needs
its documentation as it is now.

Like we have the __call__ attribute of a type, which describes
the call of the *instance*, and this differs completely from
how the type is called, would it make sense to change the
__doc__ lookup of types vs. instances in some way?

The current doc strings would probably better fit into int.__new__
or int.__init__, while the class __doc__ might talk about instances.
(although I even think no documentation would be better than
  the existing docs in the case of strings and ints, which
  show up in some object browsers, and you really don't want to
  read long musings about strings while inspecting a string value
  in the PythonWin debugger).

ciao - chris

-- 
Christian Tismer             :^)   <mailto:tismer at stackless.com>
Mission Impossible 5oftware  :     Have a break! Take a ride on Python's
Johannes-Niemeyer-Weg 9a     :    *Starship* http://starship.python.net/
14109 Berlin                 :     PGP key -> http://wwwkeys.pgp.net/
work +49 30 89 09 53 34  home +49 30 802 86 56  mobile +49 173 24 18 776
PGP 0x57F3BF04       9064 F4E1 D754 C2FF 1619  305B C09C 5A3B 57F3 BF04
      whom do you want to sponsor today?   http://www.stackless.com/