[src/trunk]: src/usr.bin/make make(1): rewrite documentation of Job

[rillig <rillig%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/537c320a6a9a
branches:  trunk
changeset: 944401:537c320a6a9a
user:      rillig <rillig%NetBSD.org@localhost>
date:      Sun Sep 27 23:12:12 2020 +0000

description:
make(1): rewrite documentation of Job

The comment above a struct is supposed to give a high-level overview.
The previous comment didn't do that but instead listed the struct fields
in declaration order in a numbered list, which was not helpful.

diffstat:

 usr.bin/make/job.h |  73 +++++++++++++++++++++++++++--------------------------
 1 files changed, 37 insertions(+), 36 deletions(-)

diffs (118 lines):

diff -r 586221ee9b9f -r 537c320a6a9a usr.bin/make/job.h
--- a/usr.bin/make/job.h        Sun Sep 27 22:17:07 2020 +0000
+++ b/usr.bin/make/job.h        Sun Sep 27 23:12:12 2020 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: job.h,v 1.51 2020/09/27 21:35:16 rillig Exp $  */
+/*     $NetBSD: job.h,v 1.52 2020/09/27 23:12:12 rillig Exp $  */
 
 /*
  * Copyright (c) 1988, 1989, 1990 The Regents of the University of California.
@@ -73,10 +73,10 @@
  *     from: @(#)job.h 8.1 (Berkeley) 6/6/93
  */
 
-/*-
- * job.h --
- *     Definitions pertaining to the running of jobs in parallel mode.
+/*
+ * Running of jobs in parallel mode.
  */
+
 #ifndef MAKE_JOB_H
 #define MAKE_JOB_H
 
@@ -110,28 +110,6 @@
  */
 #define POLL_MSEC      5000
 
-/*-
- * Job Table definitions.
- *
- * Each job has several things associated with it:
- *     1) The process id of the child shell
- *     2) The graph node describing the target being made by this job
- *     3) A LstNode for the first command to be saved after the job
- *        completes. This is NULL if there was no "..." in the job's
- *        commands.
- *     4) An FILE* for writing out the commands. This is only
- *        used before the job is actually started.
- *     5) The output is being caught via a pipe and
- *        the descriptors of our pipe, an array in which output is line
- *        buffered and the current position in that buffer are all
- *        maintained for each job.
- *     6) A word of flags which determine how the module handles errors,
- *        echoing, etc. for the job
- *
- * When a job is finished, the Make_Update function is called on each of the
- * parents of the node which was just remade. This takes care of the upward
- * traversal of the dependency graph.
- */
 struct pollfd;
 
 
@@ -139,21 +117,43 @@
 # include "meta.h"
 #endif
 
-#define JOB_BUFSIZE    1024
+/* A Job manages the shell commands that are run to create a single target.
+ * Each job is run in a separate subprocess by a shell.  Several jobs can run
+ * in parallel.
+ *
+ * The shell commands for the target are written to a temporary file,
+ * then the shell is run with the temporary file as stdin, and the output
+ * of that shell is captured via a pipe.
+ *
+ * When a job is finished, Make_Update updates all parents of the node
+ * that was just remade, marking them as ready to be made next if all
+ * other dependencies are finished as well. */
 typedef struct Job {
-    int pid;                   /* The child's process ID */
-    GNode *node;               /* The target the child is making */
-    StringListNode *tailCmds;  /* The node of the first command to be
-                                * saved when the job has been run */
-    FILE *cmdFILE;             /* When creating the shell script, this is
-                                * where the commands go */
+    /* The process ID of the shell running the commands */
+    int pid;
+
+    /* The target the child is making */
+    GNode *node;
+
+    /* If one of the shell commands is "...", all following commands are
+     * delayed until the .END node is made.  This list node points to the
+     * first of these commands, if any. */
+    StringListNode *tailCmds;
+
+    /* When creating the shell script, this is where the commands go.
+     * This is only used before the job is actually started. */
+    FILE *cmdFILE;
+
     int exit_status;           /* from wait4() in signal handler */
+
     char job_state;            /* status of the job entry */
 #define JOB_ST_FREE    0       /* Job is available */
 #define JOB_ST_SETUP   1       /* Job is allocated but otherwise invalid */
 #define JOB_ST_RUNNING 3       /* Job is running, pid valid */
 #define JOB_ST_FINISHED        4       /* Job is done (ie after SIGCHILD) */
+
     char job_suspended;
+
     short flags;               /* Flags to control treatment of job */
 #define        JOB_IGNERR      0x001   /* Ignore non-zero exits */
 #define        JOB_SILENT      0x002   /* no output */
@@ -165,10 +165,11 @@
 
     int jobPipe[2];            /* Pipe for reading output from job */
     struct pollfd *inPollfd;   /* pollfd associated with inPipe */
+
+#define JOB_BUFSIZE    1024
+    /* Buffer for storing the output of the job, line by line. */
     char outBuf[JOB_BUFSIZE + 1];
-                               /* Buffer for storing the output of the
-                                * job, line by line */
-    int curPos;                        /* Current position in op_outBuf */
+    int curPos;                        /* Current position in outBuf. */
 
 #ifdef USE_META
     struct BuildMon    bm;