[src/trunk]: src/usr.bin/make make(1): improve documentation of CachedDir and...

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

details:   https://anonhg.NetBSD.org/src/rev/8336e52ee207
branches:  trunk
changeset: 939701:8336e52ee207
user:      rillig <rillig%NetBSD.org@localhost>
date:      Sun Sep 27 22:17:07 2020 +0000

description:
make(1): improve documentation of CachedDir and Dir_AddDir

diffstat:

 usr.bin/make/dir.c |  32 +++++++++++---------------------
 usr.bin/make/dir.h |  28 +++++++++++++++++-----------
 2 files changed, 28 insertions(+), 32 deletions(-)

diffs (109 lines):

diff -r afc836eda727 -r 8336e52ee207 usr.bin/make/dir.c
--- a/usr.bin/make/dir.c        Sun Sep 27 21:39:08 2020 +0000
+++ b/usr.bin/make/dir.c        Sun Sep 27 22:17:07 2020 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: dir.c,v 1.149 2020/09/27 21:35:16 rillig Exp $ */
+/*     $NetBSD: dir.c,v 1.150 2020/09/27 22:17:07 rillig Exp $ */
 
 /*
  * Copyright (c) 1988, 1989, 1990 The Regents of the University of California.
@@ -136,7 +136,7 @@
 #include "job.h"
 
 /*     "@(#)dir.c      8.2 (Berkeley) 1/2/94"  */
-MAKE_RCSID("$NetBSD: dir.c,v 1.149 2020/09/27 21:35:16 rillig Exp $");
+MAKE_RCSID("$NetBSD: dir.c,v 1.150 2020/09/27 22:17:07 rillig Exp $");
 
 #define DIR_DEBUG0(fmt) \
     if (!DEBUG(DIR)) (void) 0; else fprintf(debug_file, fmt)
@@ -1480,27 +1480,17 @@
     return gn->mtime;
 }
 
-/*-
- *-----------------------------------------------------------------------
- * Dir_AddDir --
- *     Add the given name to the end of the given path. The order of
- *     the arguments is backwards so ParseDoDependency can do a
- *     Lst_ForEachUntil of its list of paths...
+/* Read the list of filenames in the directory and store the result
+ * in openDirectories.
+ *
+ * If a path is given, append the directory to that path.
  *
  * Input:
- *     path            the path to which the directory should be
- *                     added
- *                     XXX: Why would this ever be NULL, and what does
- *                     that mean?
- *     name            the name of the directory to add
- *
- * Results:
- *     none
- *
- * Side Effects:
- *     A structure is added to the list and the directory is
- *     read and hashed.
- *-----------------------------------------------------------------------
+ *     path            The path to which the directory should be
+ *                     added, or NULL to only add the directory to
+ *                     openDirectories
+ *     name            The name of the directory to add.
+ *                     The name is not normalized in any way.
  */
 CachedDir *
 Dir_AddDir(SearchPath *path, const char *name)
diff -r afc836eda727 -r 8336e52ee207 usr.bin/make/dir.h
--- a/usr.bin/make/dir.h        Sun Sep 27 21:39:08 2020 +0000
+++ b/usr.bin/make/dir.h        Sun Sep 27 22:17:07 2020 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: dir.h,v 1.26 2020/09/27 21:35:16 rillig Exp $  */
+/*     $NetBSD: dir.h,v 1.27 2020/09/27 22:17:07 rillig Exp $  */
 
 /*
  * Copyright (c) 1988, 1989, 1990 The Regents of the University of California.
@@ -75,21 +75,21 @@
 #ifndef        MAKE_DIR_H
 #define        MAKE_DIR_H
 
-/* A cache of a directory, remembering all the files that exist in that
- * directory. */
+/* A cache for the filenames in a directory. */
 typedef struct CachedDir {
-    char *name;                        /* Name of directory */
-    int refCount;              /* Number of paths with this directory */
-    int hits;                  /* the number of times a file in this
+    char *name;                        /* Name of directory, either absolute or
+                                * relative to the current directory.
+                                * The name is not normalized in any way,
+                                * that is, "." and "./." are different.
+                                *
+                                * Not sure what happens when .CURDIR is
+                                * assigned a new value; see Parse_DoVar. */
+    int refCount;              /* Number of SearchPaths with this directory */
+    int hits;                  /* The number of times a file in this
                                 * directory has been found */
     Hash_Table files;          /* Hash set of files in directory */
 } CachedDir;
 
-struct make_stat {
-    time_t mst_mtime;
-    mode_t mst_mode;
-};
-
 void Dir_Init(void);
 void Dir_InitDir(const char *);
 void Dir_InitCur(const char *);
@@ -110,6 +110,12 @@
 void Dir_Destroy(void *);
 void *Dir_CopyDir(void *);
 
+/* Stripped-down variant of struct stat. */
+struct make_stat {
+    time_t mst_mtime;
+    mode_t mst_mode;
+};
+
 int cached_lstat(const char *, struct make_stat *);
 int cached_stat(const char *, struct make_stat *);