[issue21309] Confusing "see also" for generic C-level __init__ methods in help output

[R. David Murray]

New submission from R. David Murray:

>>> help(ImportError.__init__)
    Help on wrapper_descriptor:

    __init__(self, /, *args, **kwargs)
        Initialize self.  See help(type(self)) for accurate signature.

The above also appears (without the wrapper_descriptor bit) in the help output for help(ImportError).  In neither case does 'help(type(self))' tell the naive user anything useful, since 'self' doesn't exist in the scope in which they are executing help.  I don't know where this text is coming from (Argument Clinic?), but it could use improvement.  I believe it is trying to say that one should see the help information for the class object.  I'm not sure how you'd spell that usefully.  Maybe "See the object's main help for a more accurate signature"?

And maybe I shouldn't have said naive user: I'm an experienced python developer, and I tried 'help(type(ImportError))', since I saw the above when I'd typed 'help(ImportError)', and it was only when I got the help for 'type' that I realized what it was trying to tell me.  Now, I tried this because the ImportError help does not in fact give the "more accurate signature", which is a different issue, but you get the point.  

We also have:

    >>> x = ImportError()
    >>> help(x.__init__)
    Help on method-wrapper object:

    __init__ = class method-wrapper(object)
     |  Methods defined here:
     |  
     |  __call__(self, /, *args, **kwargs)
     |      Call self as a function.

Maybe that's another bug?  Maybe not.

NB: in 3.3 the text is:

  |  __init__(...)
  |      x.__init__(...) initializes x; see help(type(x)) for signature

So that was worse, since the only time you would see in isolation would be when you are calling help on the class (help(ImportError.__init__)...in which case 'x' is ImportError, and type(x) is...type.  So 3.4 is *better*, but I don't think it is as good as we can do.

----------
components: Interpreter Core
messages: 216836
nosy: larry, r.david.murray
priority: normal
severity: normal
status: open
title: Confusing "see also" for generic C-level __init__ methods in help output
type: enhancement
versions: Python 3.5

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue21309>
_______________________________________