gh-85602: Add docs for generating C function signatures

[jameshcorbett]

Add documentation about how to generate nice function signatures (mostly for help and inspect) with C extension functions.

https://bugs.python.org/issue41430

• Issue: Document C docstring behavior for signature extraction #85602

[cpython-cla-bot]

The following commit authors need to sign the Contributor License Agreement:

• [email protected]

Click the button to sign:

[picnixz]

Suggested change

	The fourth entry is the function's docstring. Note the
	``"system(command)\n--\n\n"`` at the beginning. Since C extension functions
	take a fixed number of arguments---e.g. two for ``METH_VARARGS``---the Python
	interpreter has no way of knowing the function's signature until the function
	is called. However, by making the docstring start with something of the form
	``"myfunc(arg1, arg2='my_default', arg3=17)\n--\n\n"``, the signature will be
	constructed and the remainder of the docstring will be used as the function's
	``__doc__`` attribute. This can be useful for generating nice messages with the
	:func:`help` function or for getting the signature in object form with the
	:func:`inspect.signature` function.
	The fourth entry is the function's docstring. Note the
	``"system(command)\n--\n\n"`` at the beginning. Since C extension functions
	take a fixed number of arguments (for instance, two for ``METH_VARARGS``) the Python
	interpreter has no way of knowing the function's signature until the function
	is called. However, by making the docstring start with something of the form
	``"myfunc(arg1, arg2='my_default', arg3=17)\n--\n\n"``, the signature will be
	constructed and the remainder of the docstring will be used as the function's
	``__doc__`` attribute. This is typically useful for generating nice messages with
	:func:`help` or for getting the signature object with :func:`inspect.signature`.

[picnixz]

Considering that we are not yet ready to support introspection like that on our side, we don't want to expose it to users. So I'll close this PR but we can revisit it once we are fine (though we have no idea how long it will take). Thanks for the work though!