Improve comments

Author: pitrou

Modules/signalmodule.c

@@ -244,9 +244,9 @@ trip_signal(int sig_num)
     _PyEval_SignalReceived();
 
     /* And then write to the wakeup fd *after* setting all the globals and
-       doing the Py_AddPendingCall. We used to write to the wakeup fd and then
-       set the flag, but this allowed the following sequence of events
-       (especially on windows, where trip_signal runs in a new thread):
+       doing the _PyEval_SignalReceived. We used to write to the wakeup fd
+       and then set the flag, but this allowed the following sequence of events
+       (especially on windows, where trip_signal may run in a new thread):
 
        - main thread blocks on select([wakeup_fd], ...)
        - signal arrives
@@ -281,6 +281,8 @@ trip_signal(int sig_num)
                 wakeup.send_err_set = 1;
                 wakeup.send_errno = errno;
                 wakeup.send_win_error = GetLastError();
+                /* Py_AddPendingCall() isn't signal-safe, but we
+                   still use it for this exceptional case. */
                 Py_AddPendingCall(report_wakeup_send_error, NULL);
             }
         }
@@ -294,6 +296,8 @@ trip_signal(int sig_num)
             rc = _Py_write_noraise(fd, &byte, 1);
 
             if (rc < 0) {
+                /* Py_AddPendingCall() isn't signal-safe, but we
+                   still use it for this exceptional case. */
                 Py_AddPendingCall(report_wakeup_write_error,
                                   (void *)(intptr_t)errno);
             }

Python/ceval.c

@@ -392,7 +392,7 @@ _PyEval_SignalReceived(void)
 {
     /* bpo-30703: Function called when the C signal handler of Python gets a
        signal. We cannot queue a callback using Py_AddPendingCall() since this
-       function is not reentrant (use a lock and a list). */
+       function is not reentrant (uses a lock and a list). */
     SIGNAL_PENDING_CALLS();
 }
 
@@ -419,7 +419,7 @@ Py_MakePendingCalls(void)
     busy = 1;
 
     /* Python signal handler doesn't really queue a callback: it only signals
-       that an UNIX signal was received, see _PyEval_SignalReceived(). */
+       that a signal was received, see _PyEval_SignalReceived(). */
     UNSIGNAL_PENDING_CALLS();
     if (PyErr_CheckSignals() < 0) {
         SIGNAL_PENDING_CALLS();