[src/trunk]: src/usr.bin/make make(1): improve grouping of the Lst functions

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

details:   https://anonhg.NetBSD.org/src/rev/df4ec71b2085
branches:  trunk
changeset: 938127:df4ec71b2085
user:      rillig <rillig%NetBSD.org@localhost>
date:      Wed Sep 02 23:33:13 2020 +0000

description:
make(1): improve grouping of the Lst functions

Lst_IsEmpty does not belong in the "create and destroy" group, but in
"query information without modifying anything".

The functions named LstNode_* all belong together.  They do not provide
much abstraction, but still they restrict the API and hide a few struct
fields that are only used internally by Lst_Open/Lst_Close and
Lst_ForEach.

Use consistent wording in the documentation of the functions (list,
node, datum).

diffstat:

 usr.bin/make/lst.h |  174 ++++++++++++++++++++++++++--------------------------
 1 files changed, 88 insertions(+), 86 deletions(-)

diffs (202 lines):

diff -r 3c321713910a -r df4ec71b2085 usr.bin/make/lst.h
--- a/usr.bin/make/lst.h        Wed Sep 02 22:58:59 2020 +0000
+++ b/usr.bin/make/lst.h        Wed Sep 02 23:33:13 2020 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: lst.h,v 1.59 2020/08/30 11:15:05 rillig Exp $  */
+/*     $NetBSD: lst.h,v 1.60 2020/09/02 23:33:13 rillig Exp $  */
 
 /*
  * Copyright (c) 1988, 1989, 1990 The Regents of the University of California.
@@ -73,105 +73,107 @@
  *     from: @(#)lst.h 8.1 (Berkeley) 6/6/93
  */
 
-/*-
- * lst.h --
- *     Header for using the list library
- */
+/* Doubly-linked lists of arbitrary pointers. */
+
 #ifndef MAKE_LST_H
 #define MAKE_LST_H
 
-#include       <sys/param.h>
-#include       <stdlib.h>
+#include <sys/param.h>
+#include <stdlib.h>
 
-/*
- * basic typedef. This is what the Lst_ functions handle
- */
-
+/* A doubly-linked list of pointers. */
 typedef        struct List     *Lst;
+/* A single node in the doubly-linked list. */
 typedef        struct ListNode *LstNode;
 
+/* Copy a node, usually by allocating a copy of the given object.
+ * For reference-counted objects, the original object may need to be
+ * modified, therefore the parameter is not const. */
 typedef void *LstCopyProc(void *);
+/* Free the datum of a node, called before freeing the node itself. */
 typedef void LstFreeProc(void *);
-typedef Boolean LstFindProc(const void *, const void *);
-typedef int LstActionProc(void *, void *);
+/* Return TRUE if the datum matches the args, for Lst_Find. */
+typedef Boolean LstFindProc(const void *datum, const void *args);
+/* An action for Lst_ForEach. */
+typedef int LstActionProc(void *datum, void *args);
 
-/*
- * Creation/destruction functions
- */
-/* Create a new list */
-Lst            Lst_Init(void);
-/* Duplicate an existing list */
-Lst            Lst_Copy(Lst, LstCopyProc);
-/* Destroy an old one */
-void           Lst_Free(Lst);
-void           Lst_Destroy(Lst, LstFreeProc);
-/* True if list is empty */
-Boolean                Lst_IsEmpty(Lst);
+/* Create or destroy a list */
 
-/*
- * Functions to modify a list
- */
-/* Insert an element before another */
-void           Lst_InsertBefore(Lst, LstNode, void *);
-/* Place an element at the front of a lst. */
-void           Lst_Prepend(Lst, void *);
-/* Place an element at the end of a lst. */
-void           Lst_Append(Lst, void *);
-/* Remove an element */
-void           Lst_Remove(Lst, LstNode);
-/* Replace a node with a new value */
-void           LstNode_Set(LstNode, void *);
-void           LstNode_SetNull(LstNode);
+/* Create a new list. */
+Lst Lst_Init(void);
+/* Duplicate an existing list. */
+Lst Lst_Copy(Lst, LstCopyProc);
+/* Free the list, leaving the node data unmodified. */
+void Lst_Free(Lst);
+/* Free the list, freeing the node data using the given function. */
+void Lst_Destroy(Lst, LstFreeProc);
+
+/* Get information about a list */
 
-void           Lst_PrependAll(Lst, Lst);
-void           Lst_AppendAll(Lst, Lst);
-void           Lst_MoveAll(Lst, Lst);
+Boolean Lst_IsEmpty(Lst);
+/* Return the first node of the list, or NULL. */
+LstNode Lst_First(Lst);
+/* Return the last node of the list, or NULL. */
+LstNode Lst_Last(Lst);
+/* Find the first node for which the function returns TRUE, or NULL. */
+LstNode Lst_Find(Lst, LstFindProc, const void *);
+/* Find the first node for which the function returns TRUE, or NULL.
+ * The search starts at the given node, towards the end of the list. */
+LstNode Lst_FindFrom(Lst, LstNode, LstFindProc, const void *);
+/* Find the first node that contains the given datum, or NULL. */
+LstNode Lst_FindDatum(Lst, const void *);
+
+/* Modify a list */
 
-/*
- * Node-specific functions
- */
-/* Return first element in list */
-LstNode                Lst_First(Lst);
-/* Return last element in list */
-LstNode                Lst_Last(Lst);
-/* Return successor to given element */
-LstNode                LstNode_Next(LstNode);
-/* Return predecessor to given element */
-LstNode                LstNode_Prev(LstNode);
-/* Get datum from LstNode */
-void           *LstNode_Datum(LstNode);
+/* Insert a datum before the given node. */
+void Lst_InsertBefore(Lst, LstNode, void *);
+/* Place a datum at the front of the list. */
+void Lst_Prepend(Lst, void *);
+/* Place a datum at the end of the list. */
+void Lst_Append(Lst, void *);
+/* Remove the node from the list. */
+void Lst_Remove(Lst, LstNode);
+void Lst_PrependAll(Lst, Lst);
+void Lst_AppendAll(Lst, Lst);
+void Lst_MoveAll(Lst, Lst);
+
+/* Node-specific functions */
+
+/* Return the successor of the node, or NULL. */
+LstNode LstNode_Next(LstNode);
+/* Return the predecessor of the node, or NULL. */
+LstNode LstNode_Prev(LstNode);
+/* Return the datum of the node. Usually not NULL. */
+void *LstNode_Datum(LstNode);
+/* Replace the value of the node. */
+void LstNode_Set(LstNode, void *);
+/* Set the value of the node to NULL. Having NULL in a list is unusual. */
+void LstNode_SetNull(LstNode);
 
-/*
- * Functions for entire lists
- */
-/* Find an element in a list */
-LstNode                Lst_Find(Lst, LstFindProc, const void *);
-/* Find an element starting from somewhere */
-LstNode                Lst_FindFrom(Lst, LstNode, LstFindProc, const void *);
-/* Return the first node that contains the given datum, or NULL. */
-LstNode                Lst_FindDatum(Lst, const void *);
-/* Apply a function to all elements of a lst */
-int            Lst_ForEach(Lst, LstActionProc, void *);
-/* Apply a function to all elements of a lst starting from a certain point. */
-int            Lst_ForEachFrom(Lst, LstNode, LstActionProc, void *);
-/*
- * these functions are for dealing with a list as a table, of sorts.
- * An idea of the "current element" is kept and used by all the functions
- * between Lst_Open() and Lst_Close().
- */
-/* Open the list */
-void           Lst_Open(Lst);
-/* Next element please, or NULL */
-LstNode                Lst_Next(Lst);
-/* Finish table access */
-void           Lst_Close(Lst);
+/* Iterating over a list, using a callback function */
+
+/* Apply a function to each datum of the list, until the callback function
+ * returns non-zero. */
+int Lst_ForEach(Lst, LstActionProc, void *);
+/* Apply a function to each datum of the list, starting at the node,
+ * until the callback function returns non-zero. */
+int Lst_ForEachFrom(Lst, LstNode, LstActionProc, void *);
+
+/* Iterating over a list while keeping track of the current node and possible
+ * concurrent modifications */
 
-/*
- * for using the list as a queue
- */
-/* Place an element at tail of queue */
-void           Lst_Enqueue(Lst, void *);
-/* Remove an element from head of queue */
-void           *Lst_Dequeue(Lst);
+/* Start iterating the list. */
+void Lst_Open(Lst);
+/* Return the next node, or NULL. */
+LstNode Lst_Next(Lst);
+/* Finish iterating the list. */
+void Lst_Close(Lst);
+
+/* Using the list as a queue */
+
+/* Add a datum at the tail of the queue. */
+void Lst_Enqueue(Lst, void *);
+/* Remove the head node of the queue and return its datum. */
+void *Lst_Dequeue(Lst);
 
 #endif /* MAKE_LST_H */