[Python-checkins] gh-98930: improve the docstring of signal.strsignal (#99290)

[gpshead]

https://github.com/python/cpython/commit/88385b856490a5ce3c99160bde6050638f81f72e
commit: 88385b856490a5ce3c99160bde6050638f81f72e
branch: main
author: ram vikram singh <ramvikrams243 at gmail.com>
committer: gpshead <greg at krypto.org>
date: 2022-11-13T11:41:23-08:00
summary:

gh-98930: improve the docstring of signal.strsignal (#99290)

Improves the docstring on signal.strsignal to make it explain when it returns a message, None, or when it raises ValueError.

Closes #98930

Co-authored-by: Gregory P. Smith <greg at krypto.org>

files:
M Doc/library/signal.rst
M Modules/clinic/signalmodule.c.h
M Modules/signalmodule.c

diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index 2269f50cbaff..6cca760583cc 100644
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -362,9 +362,9 @@ The :mod:`signal` module defines the following functions:
 
 .. function:: strsignal(signalnum)
 
-   Return the system description of the signal *signalnum*, such as
-   "Interrupt", "Segmentation fault", etc. Returns :const:`None` if the signal
-   is not recognized.
+   Returns the description of signal *signalnum*, such as "Interrupt"
+   for :const:`SIGINT`. Returns :const:`None` if *signalnum* has no
+   description. Raises :exc:`ValueError` if *signalnum* is invalid.
 
    .. versionadded:: 3.8
 
diff --git a/Modules/clinic/signalmodule.c.h b/Modules/clinic/signalmodule.c.h
index f0276c63df18..3b3c6ba150a1 100644
--- a/Modules/clinic/signalmodule.c.h
+++ b/Modules/clinic/signalmodule.c.h
@@ -211,8 +211,9 @@ PyDoc_STRVAR(signal_strsignal__doc__,
 "\n"
 "Return the system description of the given signal.\n"
 "\n"
-"The return values can be such as \"Interrupt\", \"Segmentation fault\", etc.\n"
-"Returns None if the signal is not recognized.");
+"Returns the description of signal *signalnum*, such as \"Interrupt\"\n"
+"for :const:`SIGINT`. Returns :const:`None` if *signalnum* has no\n"
+"description. Raises :exc:`ValueError` if *signalnum* is invalid.");
 
 #define SIGNAL_STRSIGNAL_METHODDEF    \
     {"strsignal", (PyCFunction)signal_strsignal, METH_O, signal_strsignal__doc__},
@@ -704,4 +705,4 @@ signal_pidfd_send_signal(PyObject *module, PyObject *const *args, Py_ssize_t nar
 #ifndef SIGNAL_PIDFD_SEND_SIGNAL_METHODDEF
     #define SIGNAL_PIDFD_SEND_SIGNAL_METHODDEF
 #endif /* !defined(SIGNAL_PIDFD_SEND_SIGNAL_METHODDEF) */
-/*[clinic end generated code: output=f2a3321b32b0637c input=a9049054013a1b77]*/
+/*[clinic end generated code: output=2b54dc607f6e3146 input=a9049054013a1b77]*/
diff --git a/Modules/signalmodule.c b/Modules/signalmodule.c
index bdd3f4b2204e..c539787e5829 100644
--- a/Modules/signalmodule.c
+++ b/Modules/signalmodule.c
@@ -626,13 +626,14 @@ signal.strsignal
 
 Return the system description of the given signal.
 
-The return values can be such as "Interrupt", "Segmentation fault", etc.
-Returns None if the signal is not recognized.
+Returns the description of signal *signalnum*, such as "Interrupt"
+for :const:`SIGINT`. Returns :const:`None` if *signalnum* has no
+description. Raises :exc:`ValueError` if *signalnum* is invalid.
 [clinic start generated code]*/
 
 static PyObject *
 signal_strsignal_impl(PyObject *module, int signalnum)
-/*[clinic end generated code: output=44e12e1e3b666261 input=b77914b03f856c74]*/
+/*[clinic end generated code: output=44e12e1e3b666261 input=238b335847778bc0]*/
 {
     const char *res;