gh-85602: Add docs for generating C function signatures

Doc/extending/extending.rst

@@ -50,6 +50,10 @@ be callable from Python as follows:
    >>> import spam
    >>> status = spam.system("ls -l")
 
+We also want this function to be well-documented; that is, we want the
+function's :func:`help` message to appear as ``system(command)`` plus a short
+description.
+
 Begin by creating a file :file:`spammodule.c`.  (Historically, if a module is
 called ``spam``, the C file containing its implementation is called
 :file:`spammodule.c`; if the module name is very long, like ``spammify``, the
@@ -321,7 +325,7 @@ First, we need to list its name and address in a "method table"::
    static PyMethodDef SpamMethods[] = {
        ...
        {"system",  spam_system, METH_VARARGS,
-        "Execute a shell command."},
+        "system(command)\n--\n\nExecute a shell command."},
        ...
        {NULL, NULL, 0, NULL}        /* Sentinel */
    };
@@ -341,6 +345,17 @@ accept a third ``PyObject *`` parameter which will be a dictionary of keywords.
 Use :c:func:`PyArg_ParseTupleAndKeywords` to parse the arguments to such a
 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---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 method table must be referenced in the module definition structure::
 
    static struct PyModuleDef spammodule = {