Improve and correct commentary to w32proc-related data and functions.

4 files changed, 40 insertions, 15 deletions

diff --git a/src/callproc.c b/src/callproc.c
index 70e349d0d3a..e064dccd6d3 100644
--- a/src/callproc.c
+++ b/src/callproc.c
@@ -1274,7 +1274,7 @@ child_setup (int in, int out, int err, char **new_argv, bool set_pgrp,
 #ifdef WINDOWSNT
   prepare_standard_handles (in, out, err, handles);
   set_process_dir (SDATA (current_dir));
-  /* Spawn the child.  (See ntproc.c:Spawnve).  */
+  /* Spawn the child.  (See w32proc.c:sys_spawnve).  */
   cpid = spawnve (_P_NOWAIT, new_argv[0], new_argv, env);
   reset_standard_handles (in, out, err, handles);
   if (cpid == -1)
diff --git a/src/w32.c b/src/w32.c
index 7eaa38716f9..50c81f88c72 100644
--- a/src/w32.c
+++ b/src/w32.c
@@ -6085,7 +6085,8 @@ sys_pipe (int * phandles)
 }
 
 /* Function to do blocking read of one byte, needed to implement
-   select.  It is only allowed on sockets and pipes. */
+   select.  It is only allowed on communication ports, sockets, or
+   pipes. */
 int
 _sys_read_ahead (int fd)
 {
diff --git a/src/w32.h b/src/w32.h
index 23eda830268..86f9c992fe8 100644
--- a/src/w32.h
+++ b/src/w32.h
@@ -68,17 +68,41 @@ enum {
    a socket, the process handle in pi is NULL. */
 typedef struct _child_process
 {
-  int                   fd;
-  int                   pid;
-  HANDLE                char_avail;
-  HANDLE                char_consumed;
-  HANDLE                thrd;
-  HWND                  hwnd;
-  PROCESS_INFORMATION   procinfo;
-  volatile int          status;
-  char                  chr;
-  OVERLAPPED            ovl_read;
-  OVERLAPPED            ovl_write;
+  /* File descriptor for sockets and serial port connections, and for
+     reading output from async subprocesses; otherwise -1.  */
+  int                 fd;
+  /* PID for subprocess, either async or not; otherwise -1.  */
+  int                 pid;
+  /* Handle to an event object that is signaled when a read operation
+     is completed, either successfully (in which case there're indeed
+     "characters available") or not.  Used by sys_select to wait for
+     output from subprocesses or socket/serial connections.  */
+  HANDLE              char_avail;
+  /* Handle to an event that is signaled to wake up the reader thread
+     and tell it to try reading more output from a subprocess.  */
+  HANDLE              char_consumed;
+  /* Handle to the reader thread to read output from a subprocess or a
+     socket or a comm port.  */
+  HANDLE              thrd;
+  /* Handle to the console window of a subprocess.  Used to forcibly
+     terminate it by sys_kill.  */
+  HWND                hwnd;
+  /* Information about subprocess returned by CreateProcess.  Includes
+     handles to the subprocess and its primary thread, and the
+     corresponding process ID and thread ID numbers.  The PID is
+     mirrored by the 'pid' member above.  The process handle is used
+     to wait on it.  */
+  PROCESS_INFORMATION procinfo;
+  /* Status of subprocess/connection and of reading its output.  For
+     values, see the enumeration above.  */
+  volatile int        status;
+  /* Holds a single character read by _sys_read_ahead, when a
+     subprocess has some output ready.  */
+  char                chr;
+  /* Used for async read operations on serial comm ports.  */
+  OVERLAPPED          ovl_read;
+  /* Used for async write operations on serial comm ports.  */
+  OVERLAPPED          ovl_write;
 } child_process;
 
 #define MAXDESC FD_SETSIZE
diff --git a/src/w32proc.c b/src/w32proc.c
index ddc6826df98..dd8d6eb856a 100644
--- a/src/w32proc.c
+++ b/src/w32proc.c
@@ -1857,7 +1857,7 @@ sys_select (int nfds, SELECT_TYPE *rfds, SELECT_TYPE *wfds, SELECT_TYPE *efds,
           }
         else
           {
-            /* Child process and socket input */
+            /* Child process and socket/comm port input.  */
             cp = fd_info[i].cp;
             if (cp)
               {
@@ -1870,7 +1870,7 @@ sys_select (int nfds, SELECT_TYPE *rfds, SELECT_TYPE *wfds, SELECT_TYPE *efds,
                     /* Wake up the reader thread for this process */
                     cp->status = STATUS_READ_READY;
                     if (!SetEvent (cp->char_consumed))
-                      DebPrint (("nt_select.SetEvent failed with "
+                      DebPrint (("sys_select.SetEvent failed with "
                                  "%lu for fd %ld\n", GetLastError (), i));
                   }