[3.12] gh-117764: Add signatures for functions in the faulthandler module (GH-117771) (GH-117806)

miss-islington · serhiy-storchaka · web-flow · commit 0b11f0ef4f29 · 2024-04-12T10:48:55.000Z
(cherry picked from commit 245e426) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
diff --git a/Modules/faulthandler.c b/Modules/faulthandler.c
@@ -1183,58 +1183,67 @@ PyDoc_STRVAR(module_doc,
 static PyMethodDef module_methods[] = {
     {"enable",
      _PyCFunction_CAST(faulthandler_py_enable), METH_VARARGS|METH_KEYWORDS,
-     PyDoc_STR("enable(file=sys.stderr, all_threads=True): "
-               "enable the fault handler")},
+     PyDoc_STR("enable($module, /, file=sys.stderr, all_threads=True)\n--\n\n"
+               "Enable the fault handler.")},
     {"disable", faulthandler_disable_py, METH_NOARGS,
-     PyDoc_STR("disable(): disable the fault handler")},
+     PyDoc_STR("disable($module, /)\n--\n\n"
+               "Disable the fault handler.")},
     {"is_enabled", faulthandler_is_enabled, METH_NOARGS,
-     PyDoc_STR("is_enabled()->bool: check if the handler is enabled")},
+     PyDoc_STR("is_enabled($module, /)\n--\n\n"
+               "Check if the handler is enabled.")},
     {"dump_traceback",
      _PyCFunction_CAST(faulthandler_dump_traceback_py), METH_VARARGS|METH_KEYWORDS,
-     PyDoc_STR("dump_traceback(file=sys.stderr, all_threads=True): "
-               "dump the traceback of the current thread, or of all threads "
-               "if all_threads is True, into file")},
+     PyDoc_STR("dump_traceback($module, /, file=sys.stderr, all_threads=True)\n--\n\n"
+               "Dump the traceback of the current thread, or of all threads "
+               "if all_threads is True, into file.")},
     {"dump_traceback_later",
      _PyCFunction_CAST(faulthandler_dump_traceback_later), METH_VARARGS|METH_KEYWORDS,
-     PyDoc_STR("dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False):\n"
-               "dump the traceback of all threads in timeout seconds,\n"
+     PyDoc_STR("dump_traceback_later($module, /, timeout, repeat=False, file=sys.stderr, exit=False)\n--\n\n"
+               "Dump the traceback of all threads in timeout seconds,\n"
                "or each timeout seconds if repeat is True. If exit is True, "
                "call _exit(1) which is not safe.")},
     {"cancel_dump_traceback_later",
      faulthandler_cancel_dump_traceback_later_py, METH_NOARGS,
-     PyDoc_STR("cancel_dump_traceback_later():\ncancel the previous call "
-               "to dump_traceback_later().")},
+     PyDoc_STR("cancel_dump_traceback_later($module, /)\n--\n\n"
+               "Cancel the previous call to dump_traceback_later().")},
 #ifdef FAULTHANDLER_USER
     {"register",
      _PyCFunction_CAST(faulthandler_register_py), METH_VARARGS|METH_KEYWORDS,
-     PyDoc_STR("register(signum, file=sys.stderr, all_threads=True, chain=False): "
-               "register a handler for the signal 'signum': dump the "
+     PyDoc_STR("register($module, /, signum, file=sys.stderr, all_threads=True, chain=False)\n--\n\n"
+               "Register a handler for the signal 'signum': dump the "
                "traceback of the current thread, or of all threads if "
-               "all_threads is True, into file")},
+               "all_threads is True, into file.")},
     {"unregister",
-     _PyCFunction_CAST(faulthandler_unregister_py), METH_VARARGS|METH_KEYWORDS,
-     PyDoc_STR("unregister(signum): unregister the handler of the signal "
-                "'signum' registered by register()")},
+     _PyCFunction_CAST(faulthandler_unregister_py), METH_VARARGS,
+     PyDoc_STR("unregister($module, signum, /)\n--\n\n"
+               "Unregister the handler of the signal "
+               "'signum' registered by register().")},
 #endif
     {"_read_null", faulthandler_read_null, METH_NOARGS,
-     PyDoc_STR("_read_null(): read from NULL, raise "
-               "a SIGSEGV or SIGBUS signal depending on the platform")},
+     PyDoc_STR("_read_null($module, /)\n--\n\n"
+               "Read from NULL, raise "
+               "a SIGSEGV or SIGBUS signal depending on the platform.")},
     {"_sigsegv", faulthandler_sigsegv, METH_VARARGS,
-     PyDoc_STR("_sigsegv(release_gil=False): raise a SIGSEGV signal")},
+     PyDoc_STR("_sigsegv($module, release_gil=False, /)\n--\n\n"
+               "Raise a SIGSEGV signal.")},
     {"_fatal_error_c_thread", faulthandler_fatal_error_c_thread, METH_NOARGS,
-     PyDoc_STR("fatal_error_c_thread(): "
-               "call Py_FatalError() in a new C thread.")},
+     PyDoc_STR("_fatal_error_c_thread($module, /)\n--\n\n"
+               "Call Py_FatalError() in a new C thread.")},
     {"_sigabrt", faulthandler_sigabrt, METH_NOARGS,
-     PyDoc_STR("_sigabrt(): raise a SIGABRT signal")},
+     PyDoc_STR("_sigabrt($module, /)\n--\n\n"
+               "Raise a SIGABRT signal.")},
     {"_sigfpe", (PyCFunction)faulthandler_sigfpe, METH_NOARGS,
-     PyDoc_STR("_sigfpe(): raise a SIGFPE signal")},
+     PyDoc_STR("_sigfpe($module, /)\n--\n\n"
+               "Raise a SIGFPE signal.")},
 #ifdef FAULTHANDLER_STACK_OVERFLOW
     {"_stack_overflow", faulthandler_stack_overflow, METH_NOARGS,
-     PyDoc_STR("_stack_overflow(): recursive call to raise a stack overflow")},
+     PyDoc_STR("_stack_overflow($module, /)\n--\n\n"
+               "Recursive call to raise a stack overflow.")},
 #endif
 #ifdef MS_WINDOWS
     {"_raise_exception", faulthandler_raise_exception, METH_VARARGS,
-     PyDoc_STR("raise_exception(code, flags=0): Call RaiseException(code, flags).")},
+     PyDoc_STR("_raise_exception($module, code, flags=0, /)\n--\n\n"
+               "Call RaiseException(code, flags).")},
 #endif
     {NULL, NULL}  /* sentinel */
 };
