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

[Jacob Beck]

Jacob Beck added the comment:

I just got burned by this in io.StringIO, so I did a bit of looking.


This was changed in r85710aa396ef in Objects/typeobject.c. The new revision makes as much sense as the old one, which wasn't helpful either and replaced an equally unhelpful revision at some point. Some variation of this goes back at least as far back as Python2.5, which is the oldest version I have installed on my machine.


I think the real problem with this is what you touched on in the middle there. It frequently shows up on types that *don't* provide an accurate signature in their docstring or help(). For instance, io.StringIO doesn't discuss its signature at all, you have to look in the docs for the io module itself! I only figured that out after searching for it online. I think the entire exception hierarchy does it. At least in some of the more complicated exceptions you can sort of infer the arguments from the order in which the data descriptors are listed.

Based on where the message comes from I'm not sure how one could fix this. It's not clear to me that the type name is really available when this string is being calculated, since it's just a default docstring. The easiest fix might be something like "Initializes an object. There is no information about this method's call signature, help for the class may describe it". Or maybe it would be possible to write actual __init__ docstrings for some or all of the classes involved?

----------
nosy: +Jacob.Beck

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