gh-111999: Add signatures and improve docstrings for builtins

[serhiy-storchaka]

• Issue: Add signatures for some builtins #111999

[skirpichev]

Sphinx docs shows this as bool(x=False) (give impression that this is a positional-or-keyword argument). Probably, this should be adjusted too?

[serhiy-storchaka]

Maybe in other issue. The documentation not always uses syntax for positional-only parameters. It is relatively new.

[skirpichev]

BTW, for other set methods it seems there are signatures. But...

An example:

>>> help(set.add)
Help on method_descriptor:

add(self, object, /)
    Add an element to a set.

    This has no effect if the element is already present.

c.f. the sphinx docs:

add(elem)
    Add element elem to the set.

[serhiy-storchaka]

Signatures for methods without arguments and with a single positional argument are now autogenerated.

[skirpichev]

Anyway, this looks like a bug.

[serhiy-storchaka]

What exactly?

[skirpichev]

I was hoping is obvious. Instead of mystic name object, I would expect something like this

>>> inspect.signature(set.add)
<Signature (self, element, /)>
>>> help(set.add)
Help on method_descriptor:

add(self, element, /)
    Add an element to a set.

    This has no effect if the element is already present.

I realize, parameter name here is not a part of API, but I think it should be meaningful, if possible.

[serhiy-storchaka]

It could be improved, but it is not a bug. You can add explicit signatures for these methods, but for me it has low priority. I worked on support of multi-signatures, and this PR is a side product, the improvements that do not need multi-signatures (with multi-signatures and autogenerated signatures almost 100% of builtin functions and classes will have signatures).

[terryjreedy]

I think 'object', an instance of the base object class, is as correct as 'element', which is a set-theory specific synonym. We might say that 'a list has items', but item is a synonym for object. Here also, I appreciate the technically correct list.append(self, object, /). I think the consistency of the auto-generated signatures is good.

[terryjreedy]

One could argue that it should be set.add(self, hashable), as not any object can be added, whereas any object can be appended. The math term 'element' does not imply the restriction any more than 'object'.