Source-Changes-HG archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

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



details:   https://anonhg.NetBSD.org/src/rev/f8fec13952f5
branches:  trunk
changeset: 957083:f8fec13952f5
user:      rillig <rillig%NetBSD.org@localhost>
date:      Mon Nov 16 18:34:29 2020 +0000

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

diffstat:

 usr.bin/make/suff.c |  228 +++++++++++++++++++--------------------------------
 1 files changed, 84 insertions(+), 144 deletions(-)

diffs (truncated from 446 to 300 lines):

diff -r df5e2f2c4991 -r f8fec13952f5 usr.bin/make/suff.c
--- a/usr.bin/make/suff.c       Mon Nov 16 18:28:27 2020 +0000
+++ b/usr.bin/make/suff.c       Mon Nov 16 18:34:29 2020 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: suff.c,v 1.237 2020/11/16 16:15:37 rillig Exp $        */
+/*     $NetBSD: suff.c,v 1.238 2020/11/16 18:34:29 rillig Exp $        */
 
 /*
  * Copyright (c) 1988, 1989, 1990, 1993
@@ -68,36 +68,23 @@
  * SUCH DAMAGE.
  */
 
-/*-
- * suff.c --
- *     Functions to maintain suffix lists and find implicit dependents
- *     using suffix transformation rules
+/*
+ * Maintain suffix lists and find implicit dependents using suffix
+ * transformation rules such as ".c.o".
  *
  * Interface:
- *     Suff_Init       Initialize all things to do with suffixes.
- *
- *     Suff_End        Clean up the module
+ *     Suff_Init       Initialize the module.
  *
- *     Suff_DoPaths    This function is used to make life easier
- *                     when searching for a file according to its
- *                     suffix. It takes the global search path,
- *                     as defined using the .PATH: target, and appends
- *                     its directories to the path of each of the
- *                     defined suffixes, as specified using
- *                     .PATH<suffix>: targets. In addition, all
- *                     directories given for suffixes labeled as
- *                     include files or libraries, using the .INCLUDES
- *                     or .LIBS targets, are played with using
- *                     Dir_MakeFlags to create the .INCLUDES and
- *                     .LIBS global variables.
+ *     Suff_End        Clean up the module.
+ *
+ *     Suff_DoPaths    Extend the search path of each suffix to include the
+ *                     default search path.
  *
  *     Suff_ClearSuffixes
- *                     Clear out all the suffixes and defined
- *                     transformations.
+ *                     Clear out all the suffixes and transformations.
  *
  *     Suff_IsTransform
- *                     Return TRUE if the passed string is the lhs
- *                     of a transformation rule.
+ *                     See if the passed string is a transformation rule.
  *
  *     Suff_AddSuffix  Add the passed string as another known suffix.
  *
@@ -109,9 +96,7 @@
  *     Suff_AddLib     Mark the given suffix as denoting a library.
  *
  *     Suff_AddTransform
- *                     Add another transformation to the suffix
- *                     graph. Returns  GNode suitable for framing, I
- *                     mean, tacking commands, attributes, etc. on.
+ *                     Add another transformation to the suffix graph.
  *
  *     Suff_SetNull    Define the suffix to consider the suffix of
  *                     any file that doesn't have a known one.
@@ -129,7 +114,7 @@
 #include "dir.h"
 
 /*     "@(#)suff.c     8.4 (Berkeley) 3/21/94" */
-MAKE_RCSID("$NetBSD: suff.c,v 1.237 2020/11/16 16:15:37 rillig Exp $");
+MAKE_RCSID("$NetBSD: suff.c,v 1.238 2020/11/16 18:34:29 rillig Exp $");
 
 #define SUFF_DEBUG0(text) DEBUG0(SUFF, text)
 #define SUFF_DEBUG1(fmt, arg1) DEBUG1(SUFF, fmt, arg1)
@@ -149,9 +134,11 @@
 static SuffList *suffClean;    /* List of suffixes to be cleaned */
 #endif
 static SrcList *srclist;       /* List of sources */
-static GNodeList *transforms;  /* List of transformation rules */
 
-static int        sNum = 0;    /* Counter for assigning suffix numbers */
+/* List of transformation rules, such as ".c.o" */
+static GNodeList *transforms;
+
+static int sNum = 0;           /* Counter for assigning suffix numbers */
 
 typedef enum SuffFlags {
     SUFF_INCLUDE       = 0x01, /* One which is #include'd */
@@ -165,20 +152,23 @@
 
 typedef List SuffListList;
 
-/*
- * Structure describing an individual suffix.
- */
 typedef struct Suff {
-    char         *name;                /* The suffix itself, such as ".c" */
-    size_t      nameLen;       /* Length of the name, to avoid strlen calls */
-    SuffFlags   flags;         /* Type of suffix */
-    SearchPath  *searchPath;   /* The path along which files of this suffix
-                                * may be found */
-    int          sNum;         /* The suffix number */
-    int                 refCount;      /* Reference count of list membership
-                                * and several other places */
-    SuffList    *parents;      /* Suffixes we have a transformation to */
-    SuffList    *children;     /* Suffixes we have a transformation from */
+    /* The suffix itself, such as ".c" */
+    char *name;
+    /* Length of the name, to avoid strlen calls */
+    size_t nameLen;
+    /* Type of suffix */
+    SuffFlags flags;
+    /* The path along which files of this suffix may be found */
+    SearchPath *searchPath;
+    /* The suffix number; TODO: document the purpose of this number */
+    int sNum;
+    /* Reference count of list membership and several other places */
+    int refCount;
+    /* Suffixes we have a transformation to */
+    SuffList *parents;
+    /* Suffixes we have a transformation from */
+    SuffList *children;
 
     /* Lists in which this suffix is referenced.
      * XXX: These lists are used nowhere, they are just appended to, for no
@@ -203,30 +193,19 @@
 #endif
 } Src;
 
-static Suff *suffNull;         /* The NULL suffix for this run */
-static Suff *emptySuff;                /* The empty suffix required for POSIX
-                                * single-suffix transformation rules */
+/* TODO: Document the difference between suffNull and emptySuff. */
+/* The NULL suffix for this run */
+static Suff *suffNull;
+/* The empty suffix required for POSIX single-suffix transformation rules */
+static Suff *emptySuff;
 
 
 static void SuffFindDeps(GNode *, SrcList *);
 static void SuffExpandWildcards(GNodeListNode *, GNode *);
 
-       /*************** Lst Predicates ****************/
-/*-
- *-----------------------------------------------------------------------
- * SuffStrIsPrefix  --
- *     See if pref is a prefix of str.
- *
- * Input:
- *     pref            possible prefix
- *     str             string to check
- *
- * Results:
- *     NULL if it ain't, pointer to character in str after prefix if so
- *
- * Side Effects:
- *     None
- *-----------------------------------------------------------------------
+/*
+ * See if pref is a prefix of str.
+ * Return NULL if it ain't, pointer to character in str after prefix if so.
  */
 static const char *
 SuffStrIsPrefix(const char *pref, const char *str)
@@ -239,15 +218,9 @@
     return *pref ? NULL : str;
 }
 
-/* See if suff is a suffix of str.
- *
- * Input:
- *     s               possible suffix
- *     nameLen         length of the string to examine
- *     nameEnd         end of the string to examine
- *
- * Results:
- *     NULL if it ain't, pointer to the start of suffix in str if it is.
+/*
+ * See if suff is a suffix of name.
+ * Return NULL if it ain't, pointer to the start of suffix in name if it is.
  */
 static const char *
 SuffSuffGetSuffix(const Suff *s, size_t nameLen, const char *nameEnd)
@@ -307,8 +280,6 @@
     return NULL;
 }
 
-           /*********** Maintenance Functions ************/
-
 static void
 SuffUnRef(SuffList *list, Suff *suff)
 {
@@ -353,13 +324,14 @@
 {
     SuffUnRef(list, suff);
     if (suff->refCount == 0) {
+       /* XXX: can lead to suff->refCount == -1 */
        SuffUnRef(sufflist, suff);
        SuffFree(suff);
     }
 }
 
 /* Insert the suffix into the list, keeping the list ordered by suffix
- * numbers. */
+ * number. */
 static void
 SuffInsert(SuffList *list, Suff *suff)
 {
@@ -402,16 +374,18 @@
     suff->ref = Lst_New();
     suff->sNum = sNum++;
     suff->flags = 0;
-    suff->refCount = 1;
+    suff->refCount = 1; /* XXX: why 1? It's not assigned anywhere yet. */
 
     return suff;
 }
 
-/* This is gross. Nuke the list of suffixes but keep all transformation
- * rules around. The transformation graph is destroyed in this process, but
- * we leave the list of rules so when a new graph is formed the rules will
- * remain. This function is called from the parse module when a .SUFFIXES:\n
- * line is encountered. */
+/*
+ * Nuke the list of suffixes but keep all transformation rules around. The
+ * transformation graph is destroyed in this process, but we leave the list
+ * of rules so when a new graph is formed, the rules will remain. This
+ * function is called when a line '.SUFFIXES:' with an empty suffixes list is
+ * encountered in a makefile.
+ */
 void
 Suff_ClearSuffixes(void)
 {
@@ -482,7 +456,8 @@
 }
 
 /* Return TRUE if the given string is a transformation rule, that is, a
- * concatenation of two known suffixes. */
+ * concatenation of two known suffixes such as ".c.o" or a single suffix
+ * such as ".o". */
 Boolean
 Suff_IsTransform(const char *str)
 {
@@ -562,6 +537,7 @@
 {
     if ((gn->type & OP_DOUBLEDEP) && !Lst_IsEmpty(gn->cohorts))
        gn = gn->cohorts->last->datum;
+
     if ((gn->type & OP_TRANSFORM) && Lst_IsEmpty(gn->commands) &&
        Lst_IsEmpty(gn->children))
     {
@@ -743,14 +719,18 @@
     return s != NULL ? s->searchPath : NULL;
 }
 
-/* Extend the search paths for all suffixes to include the default search
- * path.
+/*
+ * Extend the search paths for all suffixes to include the default search
+ * path (dirSearchPath).
  *
- * The searchPath field of all the suffixes is extended by the directories
- * in dirSearchPath. If paths were specified for the ".h" suffix, the
- * directories are stuffed into a global variable called ".INCLUDES" with
- * each directory preceded by a -I. The same is done for the ".a" suffix,
- * except the variable is called ".LIBS" and the flag is -L.
+ * The default search path can be defined using the special target '.PATH'.
+ * The search path of each suffix can be defined using the special target
+ * '.PATH<suffix>'.
+ *
+ * If paths were specified for the ".h" suffix, the directories are stuffed
+ * into a global variable called ".INCLUDES" with each directory preceded by
+ * '-I'. The same is done for the ".a" suffix, except the variable is called
+ * ".LIBS" and the flag is '-L'.
  */
 void
 Suff_DoPaths(void)
@@ -873,7 +853,7 @@
 
 /* Add a suffix as a Src structure to the given list with its parent
  * being the given Src structure. If the suffix is the null suffix,
- * the prefix is used unaltered as the file name in the Src structure.
+ * the prefix is used unaltered as the filename in the Src structure.
  *
  * Input:
  *     suff            suffix for which to create a Src structure
@@ -894,12 +874,7 @@
     SuffAddSrc(suff, srcList, targ, str_concat2(targ->pref, suff->name), "2");
 }
 
-/* Add all the children of targ as Src structures to the given list.
- *
- * Input:
- *     l               list to which to add the new level
- *     targ            Src structure to use as the parent
- */
+/* Add all the children of targ to the list. */
 static void



Home | Main Index | Thread Index | Old Index