[src/trunk]: src/usr.bin/make make(1): document Suffix and Src

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

details:   https://anonhg.NetBSD.org/src/rev/7f8d50481e2c
branches:  trunk
changeset: 1016480:7f8d50481e2c
user:      rillig <rillig%NetBSD.org@localhost>
date:      Sat Nov 21 20:04:10 2020 +0000

description:
make(1): document Suffix and Src

diffstat:

 usr.bin/make/suff.c |  17 ++++++++++++++---
 1 files changed, 14 insertions(+), 3 deletions(-)

diffs (52 lines):

diff -r 3609aa64bae2 -r 7f8d50481e2c usr.bin/make/suff.c
--- a/usr.bin/make/suff.c       Sat Nov 21 19:57:35 2020 +0000
+++ b/usr.bin/make/suff.c       Sat Nov 21 20:04:10 2020 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: suff.c,v 1.272 2020/11/21 19:40:19 rillig Exp $        */
+/*     $NetBSD: suff.c,v 1.273 2020/11/21 20:04:10 rillig Exp $        */
 
 /*
  * Copyright (c) 1988, 1989, 1990, 1993
@@ -114,7 +114,7 @@
 #include "dir.h"
 
 /*     "@(#)suff.c     8.4 (Berkeley) 3/21/94" */
-MAKE_RCSID("$NetBSD: suff.c,v 1.272 2020/11/21 19:40:19 rillig Exp $");
+MAKE_RCSID("$NetBSD: suff.c,v 1.273 2020/11/21 20:04:10 rillig Exp $");
 
 #define SUFF_DEBUG0(text) DEBUG0(SUFF, text)
 #define SUFF_DEBUG1(fmt, arg1) DEBUG1(SUFF, fmt, arg1)
@@ -152,6 +152,10 @@
 
 typedef List SuffixListList;
 
+/*
+ * A suffix such as ".c" or ".o" that is used in suffix transformation rules
+ * such as ".c.o:".
+ */
 typedef struct Suffix {
     /* The suffix itself, such as ".c" */
     char *name;
@@ -178,7 +182,13 @@
 } Suffix;
 
 /*
- * Structure used in the search for implied sources.
+ * A candidate when searching for implied sources.
+ *
+ * For example, when "src.o" is to be made, a typical candidate is "src.c"
+ * via the transformation rule ".c.o".  If that doesn't exist, maybe there is
+ * another transformation rule ".pas.c" that would make "src.pas" an indirect
+ * candidate as well.  The first such chain that leads to an existing file or
+ * node is finally made.
  */
 typedef struct Src {
     char *file;                        /* The file to look for */
@@ -193,6 +203,7 @@
 #endif
 } Src;
 
+
 /* TODO: Document the difference between nullSuff and emptySuff. */
 /* The NULL suffix for this run */
 static Suffix *nullSuff;