document a bit of job.c

notice that Job_Finish() really returns a boolean, so unconfuse
that accordingly (it's likely the extra Fatal() message is not
needed and we could just call finish)

3 files changed, 35 insertions, 12 deletions

diff --git a/usr.bin/make/job.c b/usr.bin/make/job.c
index 98532323edf..d60f04b9fe8 100644
--- a/usr.bin/make/job.c
+++ b/usr.bin/make/job.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: job.c,v 1.133 2012/11/24 11:05:33 espie Exp $	*/
+/*	$OpenBSD: job.c,v 1.134 2012/12/08 12:54:17 espie Exp $	*/
 /*	$NetBSD: job.c,v 1.16 1996/11/06 17:59:08 christos Exp $	*/
 
 /*
@@ -129,7 +129,7 @@ static bool	no_new_jobs;	/* Mark recursive shit so we shouldn't start
 Job *runningJobs;		/* Jobs currently running a process */
 Job *errorJobs;			/* Jobs in error at end */
 static Job *heldJobs;		/* Jobs not running yet because of expensive */
-static pid_t mypid;
+static pid_t mypid;		/* Used for printing debugging messages */
 
 static volatile sig_atomic_t got_fatal;
 
@@ -979,17 +979,17 @@ handle_fatal_signal(int signo)
 bool
 Job_Finish(void)
 {
-	bool errors = errorJobs != NULL;
+	bool problem = errorJobs != NULL;
 
 	if ((end_node->type & OP_DUMMY) == 0) {
-		if (errors) {
+		if (problem) {
 			Error("Errors reported so .END ignored");
 		} else {
 			Job_Make(end_node);
 			loop_handle_running_jobs();
 		}
 	}
-	return errors;
+	return problem;
 }
 
 void
diff --git a/usr.bin/make/job.h b/usr.bin/make/job.h
index 46957590e2a..4ddfca413ee 100644
--- a/usr.bin/make/job.h
+++ b/usr.bin/make/job.h
@@ -1,7 +1,7 @@
 #ifndef _JOB_H_
 #define _JOB_H_
 
-/*	$OpenBSD: job.h,v 1.29 2012/12/07 15:08:58 espie Exp $	*/
+/*	$OpenBSD: job.h,v 1.30 2012/12/08 12:54:17 espie Exp $	*/
 /*	$NetBSD: job.h,v 1.5 1996/11/06 17:59:10 christos Exp $ */
 
 /*
@@ -45,11 +45,34 @@
  *	Definitions pertaining to the running of jobs.
  */
 
+/* Job_Make(gn);
+ *	register a new job running commands associated with building gn.
+ */
 extern void Job_Make(GNode *);
+/* Job_Init(maxproc);
+ *	setup job handling framework
+ */
 extern void Job_Init(int);
+
+/* interface with the normal build in make.c */
+/* okay = can_start_job();
+ *	can we run new jobs right now ?
+ */
 extern bool can_start_job(void);
+
+/* finished = Job_Empty();
+ *	wait until all jobs are finished after we build everything.
+ */
 extern bool Job_Empty(void);
-extern int Job_Finish(void);
+
+/* errors = Job_Finish();
+ *	final processing including running .END target if no errors.
+ */
+extern bool Job_Finish(void);
+
+/* Job_Begin();
+ *	similarly, run .BEGIN job at start of job.
+ */
 extern void Job_Begin(void);
 
 extern void Job_Wait(void);
diff --git a/usr.bin/make/make.c b/usr.bin/make/make.c
index 402edebb2e0..12c406a449f 100644
--- a/usr.bin/make/make.c
+++ b/usr.bin/make/make.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: make.c,v 1.64 2012/10/09 19:49:28 espie Exp $	*/
+/*	$OpenBSD: make.c,v 1.65 2012/12/08 12:54:17 espie Exp $	*/
 /*	$NetBSD: make.c,v 1.10 1996/11/06 17:59:15 christos Exp $	*/
 
 /*
@@ -572,7 +572,7 @@ add_targets_to_make(Lst todo)
 bool
 Make_Run(Lst targs)		/* the initial list of targets */
 {
-	int errors;	/* Number of errors the Job module reports */
+	bool problem;	/* errors occurred */
 	GNode *gn;
 	unsigned int i;
 	bool cycle;
@@ -619,7 +619,7 @@ Make_Run(Lst targs)		/* the initial list of targets */
 		(void)MakeStartJobs();
 	}
 
-	errors = Job_Finish();
+	problem = Job_Finish();
 	cycle = false;
 
 	for (gn = ohash_first(&targets, &i); gn != NULL; 
@@ -627,7 +627,7 @@ Make_Run(Lst targs)		/* the initial list of targets */
 	    	if (has_been_built(gn))
 			continue;
 		cycle = true;
-		errors++;
+		problem = true;
 	    	printf("Error: target %s unaccounted for (%s)\n", 
 		    gn->name, status_to_string(gn));
 	}
@@ -636,7 +636,7 @@ Make_Run(Lst targs)		/* the initial list of targets */
 	 * because some inferior reported an error.
 	 */
 	Lst_ForEach(targs, MakePrintStatus, &cycle);
-	if (errors)
+	if (problem)
 		Fatal("Errors while building");
 
 	return true;