When a function has only positional arguments and at least one argument is optional, the expected signature is:

  func(mandatory_arg1, mandatory_arg2[, optional_arg3[, optinal_arg4]])

For example, the signature of format() is inconsistent with its documentation.

Signature:
---
$ python3 -c 'help(format)'|cat
Help on built-in function format in module builtins:

format(value, format_spec='', /)
    Return value.__format__(format_spec)
    
    format_spec defaults to the empty string
---

Documentation:
---
.. function:: format(value[, format_spec])
---

Attached patch is a first attempt to fix the issue. The problem is that my heuristic to check if an argument is "optional" doesn't seem to work as expected in all cases. I chose to check if the C default is NULL.

The problem is that some functions defines a C default to NULL whereas the Python default is set to a different value and is correct.

Example with _io.FileIO.truncate:

    /*[clinic input]
    _io.FileIO.truncate
        size as posobj: object = NULL
        /

whereas the documentation says that the default is None:

   .. method:: truncate(size=None)

It's easy to fix the default, but in this case my change doesn't fix the signature anymore since the C default is still NULL:

    /*[clinic input]
    _io.FileIO.truncate
        size as posobj: object(c_default="NULL") = None
        /

We need a different heuristic than C default is NULL, or we should fix functions where the heuristic fails.