[src/trunk]: src/usr.bin/make make(1): clean up comments in job.c and make.c

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

details:   https://anonhg.NetBSD.org/src/rev/f3568bbf77cb
branches:  trunk
changeset: 955341:f3568bbf77cb
user:      rillig <rillig%NetBSD.org@localhost>
date:      Sun Sep 27 11:14:03 2020 +0000

description:
make(1): clean up comments in job.c and make.c

diffstat:

 usr.bin/make/job.c  |  383 +++++++++------------------------------------------
 usr.bin/make/make.c |  306 ++++++++++------------------------------
 2 files changed, 152 insertions(+), 537 deletions(-)

diffs (truncated from 1113 to 300 lines):

diff -r dc3053e693cc -r f3568bbf77cb usr.bin/make/job.c
--- a/usr.bin/make/job.c        Sun Sep 27 10:35:57 2020 +0000
+++ b/usr.bin/make/job.c        Sun Sep 27 11:14:03 2020 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: job.c,v 1.242 2020/09/26 17:39:45 rillig Exp $ */
+/*     $NetBSD: job.c,v 1.243 2020/09/27 11:14:03 rillig Exp $ */
 
 /*
  * Copyright (c) 1988, 1989, 1990 The Regents of the University of California.
@@ -140,7 +140,7 @@
 #include "trace.h"
 
 /*     "@(#)job.c      8.2 (Berkeley) 3/19/94" */
-MAKE_RCSID("$NetBSD: job.c,v 1.242 2020/09/26 17:39:45 rillig Exp $");
+MAKE_RCSID("$NetBSD: job.c,v 1.243 2020/09/27 11:14:03 rillig Exp $");
 
 # define STATIC static
 
@@ -162,12 +162,18 @@
 /*
  * XXX: Avoid SunOS bug... FILENO() is fp->_file, and file
  * is a char! So when we go above 127 we turn negative!
+ *
+ * XXX: This cannot have ever worked. Converting a signed char directly to
+ * unsigned creates very large numbers. It should have been converted to
+ * unsigned char first, in the same way as for the <ctype.h> functions.
  */
 #define FILENO(a) ((unsigned) fileno(a))
 
-static int               numCommands;      /* The number of commands actually printed
-                                    * for a target. Should this number be
-                                    * 0, no shell will be executed. */
+/* The number of commands actually printed for a target.
+ * XXX: Why printed? Shouldn't that be run/printed instead, depending on the
+ * command line options?
+ * Should this number be 0, no shell will be executed. */
+static int               numCommands;
 
 /*
  * Return values from JobStart.
@@ -181,7 +187,7 @@
  *
  * The build environment may set DEFSHELL_INDEX to one of
  * DEFSHELL_INDEX_SH, DEFSHELL_INDEX_KSH, or DEFSHELL_INDEX_CSH, to
- * select one of the prefedined shells as the default shell.
+ * select one of the predefined shells as the default shell.
  *
  * Alternatively, the build environment may set DEFSHELL_CUSTOM to the
  * name or the full path of a sh-compatible shell, which will be used as
@@ -269,14 +275,12 @@
     NULL, NULL,
 }
 };
-static Shell *commandShell = &shells[DEFSHELL_INDEX]; /* this is the shell to
-                                                  * which we pass all
-                                                  * commands in the Makefile.
-                                                  * It is set by the
-                                                  * Job_ParseShell function */
-const char *shellPath = NULL,                    /* full pathname of
-                                                  * executable image */
-          *shellName = NULL;                     /* last component of shell */
+
+/* This is the shell to which we pass all commands in the Makefile.
+ * It is set by the Job_ParseShell function. */
+static Shell *commandShell = &shells[DEFSHELL_INDEX];
+const char *shellPath = NULL;  /* full pathname of executable image */
+const char *shellName = NULL;  /* last component of shellPath */
 char *shellErrFlag = NULL;
 static char *shellArgv = NULL; /* Custom shell args */
 
@@ -427,19 +431,7 @@
        Punt("Cannot set flags: %s", strerror(errno));
 }
 
-/*-
- *-----------------------------------------------------------------------
- * JobCondPassSig --
- *     Pass a signal to a job
- *
- * Input:
- *     signop          Signal to send it
- *
- * Side Effects:
- *     None, except the job may bite it.
- *
- *-----------------------------------------------------------------------
- */
+/* Pass the signal to each running job. */
 static void
 JobCondPassSig(int signo)
 {
@@ -461,23 +453,9 @@
     }
 }
 
-/*-
- *-----------------------------------------------------------------------
- * JobChldSig --
- *     SIGCHLD handler.
- *
- * Input:
- *     signo           The signal number we've received
+/* SIGCHLD handler.
  *
- * Results:
- *     None.
- *
- * Side Effects:
- *     Sends a token on the child exit pipe to wake us up from
- *     select()/poll().
- *
- *-----------------------------------------------------------------------
- */
+ * Sends a token on the child exit pipe to wake us up from select()/poll(). */
 static void
 JobChildSig(int signo MAKE_ATTR_UNUSED)
 {
@@ -486,22 +464,7 @@
 }
 
 
-/*-
- *-----------------------------------------------------------------------
- * JobContinueSig --
- *     Resume all stopped jobs.
- *
- * Input:
- *     signo           The signal number we've received
- *
- * Results:
- *     None.
- *
- * Side Effects:
- *     Jobs start running again.
- *
- *-----------------------------------------------------------------------
- */
+/* Resume all stopped jobs. */
 static void
 JobContinueSig(int signo MAKE_ATTR_UNUSED)
 {
@@ -514,22 +477,8 @@
        continue;
 }
 
-/*-
- *-----------------------------------------------------------------------
- * JobPassSig --
- *     Pass a signal on to all jobs, then resend to ourselves.
- *
- * Input:
- *     signo           The signal number we've received
- *
- * Results:
- *     None.
- *
- * Side Effects:
- *     We die by the same signal.
- *
- *-----------------------------------------------------------------------
- */
+/* Pass a signal on to all jobs, then resend to ourselves.
+ * We die by the same signal. */
 MAKE_ATTR_DEAD static void
 JobPassSig_int(int signo)
 {
@@ -537,6 +486,8 @@
     JobInterrupt(TRUE, signo);
 }
 
+/* Pass a signal on to all jobs, then resend to ourselves.
+ * We die by the same signal. */
 MAKE_ATTR_DEAD static void
 JobPassSig_term(int signo)
 {
@@ -602,24 +553,6 @@
     (void)sigprocmask(SIG_SETMASK, &omask, NULL);
 }
 
-/*-
- *-----------------------------------------------------------------------
- * JobFindPid  --
- *     Compare the pid of the job with the given pid and return 0 if they
- *     are equal. This function is called from Job_CatchChildren
- *     to find the job descriptor of the finished job.
- *
- * Input:
- *     job             job to examine
- *     pid             process id desired
- *
- * Results:
- *     Job with matching pid
- *
- * Side Effects:
- *     None
- *-----------------------------------------------------------------------
- */
 static Job *
 JobFindPid(int pid, int status, Boolean isJobs)
 {
@@ -655,7 +588,7 @@
  *     jobp            job for which to print it
  *
  * Results:
- *     Always 0, unless the command was "..."
+ *     0, unless the command was "..."
  *
  * Side Effects:
  *     If the command begins with a '-' and the shell has no error control,
@@ -897,19 +830,7 @@
 }
 
 
-/*-
- *-----------------------------------------------------------------------
- * JobClose --
- *     Called to close both input and output pipes when a job is finished.
- *
- * Results:
- *     Nada
- *
- * Side Effects:
- *     The file descriptors associated with the job are closed.
- *
- *-----------------------------------------------------------------------
- */
+/* Called to close both input and output pipes when a job is finished. */
 static void
 JobClose(Job *job)
 {
@@ -936,9 +857,6 @@
  *     job             job to finish
  *     status          sub-why job went away
  *
- * Results:
- *     None
- *
  * Side Effects:
  *     Final commands for the job are placed on postCommands.
  *
@@ -948,7 +866,6 @@
  *     to ABORT_ERROR so no more jobs will be started.
  *-----------------------------------------------------------------------
  */
-/*ARGSUSED*/
 static void
 JobFinish(Job *job, int status)
 {
@@ -1111,24 +1028,10 @@
     }
 }
 
-/*-
- *-----------------------------------------------------------------------
- * Job_Touch --
- *     Touch the given target. Called by JobStart when the -t flag was
- *     given
+/* Touch the given target. Called by JobStart when the -t flag was given.
  *
- * Input:
- *     gn              the node of the file to touch
- *     silent          TRUE if should not print message
- *
- * Results:
- *     None
- *
- * Side Effects:
- *     The data modification of the file is changed. In addition, if the
- *     file did not exist, it is created.
- *-----------------------------------------------------------------------
- */
+ * The modification date of the file is changed.
+ * If the file did not exist, it is created. */
 void
 Job_Touch(GNode *gn, Boolean silent)
 {
@@ -1187,10 +1090,10 @@
     }
 }
 
-/*-
- *-----------------------------------------------------------------------
- * Job_CheckCommands --
- *     Make sure the given node has all the commands it needs.
+/* Make sure the given node has all the commands it needs.
+ *
+ * The node will have commands from the .DEFAULT rule added to it if it
+ * needs them.
  *
  * Input:
  *     gn              The target whose commands need verifying
@@ -1198,11 +1101,6 @@
  *
  * Results:
  *     TRUE if the commands list is/was ok.
- *
- * Side Effects:
- *     The node will have commands from the .DEFAULT rule added to it
- *     if it needs them.
- *-----------------------------------------------------------------------