[docs] [issue20285] Improve object.__doc__ and help(object) output

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

Reponses on the pydev thread, which include 3 other coredevs:

"a base for all classes." object entry in lib ref, function
"the ultimate base class of all other classes."  Martin Panter

object is neither a base or superclass of itself, so the first of each pair above is not quite right.

"the base class of the class heirarchy ['hierarchy']"  Steven D'Aprano
"the root of the class heirarchy"  ditto
+ quotes from Java and Ruby

Jeff Allen and Barry Warsaw like either, with BW slightly referring the first.

I was thinking about 'tree' instead of 'hierachy', but 'class tree' is wrong and 'directed acyclic graph of classes' a bit wordy.  While hierarchies are often thought of as trees, it is possible for someone to report to more than one person.

No one supported the status quo.

Martin also suggested a continuation:  "When called, it accepts no
arguments and returns a new unique and featureless object."

Even though object, unlike any other class, is primarily used as a base class rather than instance source, the latter should be included.  For other built-in classes, the summary line describes instances. I would leave out 'unique' as that could be confused with 'singleton'.


I propose the following, which follows general docstring format, but describes the class instead of instances in the summary line.

"The base class of the class hierarchy.

When called, it accepts no arguments and returns a new featureless instance that has no instance attributes and cannot be given any."

Passing arguments to object and trying to add attributes to object instances are two common beginner mistakes.

----------
versions: +Python 3.6, Python 3.7

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