[src/trunk]: src/usr.bin/make make(1): condense the API comments in the list ...

To: source-changes-hg%NetBSD.org@localhost
Subject: [src/trunk]: src/usr.bin/make make(1): condense the API comments in the list ...
From: rillig <rillig%NetBSD.org@localhost>
Date: Sun, 15 Nov 2020 14:55:14 +0000
details:   https://anonhg.NetBSD.org/src/rev/c2d8ecbb21a1
branches:  trunk
changeset: 942873:c2d8ecbb21a1
user:      rillig <rillig%NetBSD.org@localhost>
date:      Fri Aug 21 06:28:38 2020 +0000

description:
make(1): condense the API comments in the list library

Most mentioned "side effects" were either implementation details or
rather "main effects".  The wording of similar functions has been
aligned.

diffstat:

 usr.bin/make/lst.c |  350 +++++++---------------------------------------------
 1 files changed, 49 insertions(+), 301 deletions(-)

diffs (truncated from 521 to 300 lines):

diff -r 802e25a869e1 -r c2d8ecbb21a1 usr.bin/make/lst.c
--- a/usr.bin/make/lst.c        Fri Aug 21 06:27:41 2020 +0000
+++ b/usr.bin/make/lst.c        Fri Aug 21 06:28:38 2020 +0000
@@ -1,4 +1,4 @@
-/* $NetBSD: lst.c,v 1.13 2020/08/21 05:28:41 rillig Exp $ */
+/* $NetBSD: lst.c,v 1.14 2020/08/21 06:28:38 rillig Exp $ */
 
 /*
  * Copyright (c) 1988, 1989, 1990, 1993
@@ -38,11 +38,11 @@
 #include "make_malloc.h"
 
 #ifndef MAKE_NATIVE
-static char rcsid[] = "$NetBSD: lst.c,v 1.13 2020/08/21 05:28:41 rillig Exp $";
+static char rcsid[] = "$NetBSD: lst.c,v 1.14 2020/08/21 06:28:38 rillig Exp $";
 #else
 #include <sys/cdefs.h>
 #ifndef lint
-__RCSID("$NetBSD: lst.c,v 1.13 2020/08/21 05:28:41 rillig Exp $");
+__RCSID("$NetBSD: lst.c,v 1.14 2020/08/21 06:28:38 rillig Exp $");
 #endif /* not lint */
 #endif
 
@@ -74,20 +74,14 @@
                                 * Lst_Remove */
 };
 
-/*
- * LstValid --
- *     Return TRUE if the list is valid
- */
+/* Return TRUE if the list is valid. */
 static Boolean
 LstValid(Lst l)
 {
     return l != NULL;
 }
 
-/*
- * LstNodeValid --
- *     Return TRUE if the list node is valid
- */
+/* Return TRUE if the list node is valid. */
 static Boolean
 LstNodeValid(LstNode ln)
 {
@@ -106,10 +100,7 @@
     return ln;
 }
 
-/*
- * LstIsEmpty (l) --
- *     TRUE if the list l is empty.
- */
+/* Return TRUE if the list is empty. */
 static Boolean
 LstIsEmpty(Lst l)
 {
@@ -130,23 +121,10 @@
     return nList;
 }
 
-/*-
- *-----------------------------------------------------------------------
- * Lst_Duplicate --
- *     Duplicate an entire list. If a function to copy a void *is
- *     given, the individual client elements will be duplicated as well.
- *
- * Input:
- *     l               the list to duplicate
- *     copyProc        A function to duplicate each void *
- *
- * Results:
- *     The new Lst structure or NULL if failure.
- *
- * Side Effects:
- *     A new list is created.
- *-----------------------------------------------------------------------
- */
+/* Duplicate an entire list, usually by copying the datum pointers.
+ * If copyProc is given, that function is used to create the new datum from the
+ * old datum, usually by creating a copy of it.
+ * Return the new list, or NULL on failure. */
 Lst
 Lst_Duplicate(Lst l, DuplicateProc *copyProc)
 {
@@ -179,21 +157,8 @@
     return nl;
 }
 
-/*-
- *-----------------------------------------------------------------------
- * Lst_Destroy --
- *     Destroy a list and free all its resources. If the freeProc is
- *     given, it is called with the datum from each node in turn before
- *     the node is freed.
- *
- * Results:
- *     None.
- *
- * Side Effects:
- *     The given list is freed in its entirety.
- *
- *-----------------------------------------------------------------------
- */
+/* Destroy a list and free all its resources. If the freeProc is given, it is
+ * called with the datum from each node in turn before the node is freed. */
 void
 Lst_Destroy(Lst list, FreeProc *freeProc)
 {
@@ -231,26 +196,8 @@
  * Functions to modify a list
  */
 
-/*-
- *-----------------------------------------------------------------------
- * Lst_InsertBefore --
- *     Insert a new node with the given piece of data before the given
- *     node in the given list.
- *
- * Input:
- *     l               list to manipulate
- *     ln              node before which to insert d
- *     d               datum to be inserted
- *
- * Results:
- *     SUCCESS or FAILURE.
- *
- * Side Effects:
- *     the firstPtr field will be changed if ln is the first node in the
- *     list.
- *
- *-----------------------------------------------------------------------
- */
+/* Insert a new node with the given piece of data before the given node in the
+ * given list. */
 ReturnStatus
 Lst_InsertBefore(Lst l, LstNode ln, void *d)
 {
@@ -292,27 +239,8 @@
     return SUCCESS;
 }
 
-/*-
- *-----------------------------------------------------------------------
- * Lst_InsertAfter --
- *     Create a new node and add it to the given list after the given node.
- *
- * Input:
- *     l               affected list
- *     ln              node after which to append the datum
- *     d               said datum
- *
- * Results:
- *     SUCCESS if all went well.
- *
- * Side Effects:
- *     A new ListNode is created and linked in to the List. The lastPtr
- *     field of the List will be altered if ln is the last node in the
- *     list. lastPtr and firstPtr will alter if the list was empty and
- *     ln was NULL.
- *
- *-----------------------------------------------------------------------
- */
+/* Insert a new node with the given piece of data after the given node in the
+ * given list. */
 ReturnStatus
 Lst_InsertAfter(Lst l, LstNode ln, void *d)
 {
@@ -354,20 +282,7 @@
     return SUCCESS;
 }
 
-/*-
- *-----------------------------------------------------------------------
- * Lst_AtFront --
- *     Place a piece of data at the front of a list
- *
- * Results:
- *     SUCCESS or FAILURE
- *
- * Side Effects:
- *     A new ListNode is created and stuck at the front of the list.
- *     hence, firstPtr (and possible lastPtr) in the list are altered.
- *
- *-----------------------------------------------------------------------
- */
+/* Add a piece of data at the front of the given list. */
 ReturnStatus
 Lst_AtFront(Lst l, void *d)
 {
@@ -377,23 +292,7 @@
     return Lst_InsertBefore(l, front, d);
 }
 
-/*-
- *-----------------------------------------------------------------------
- * Lst_AtEnd --
- *     Add a node to the end of the given list
- *
- * Input:
- *     l               List to which to add the datum
- *     d               Datum to add
- *
- * Results:
- *     SUCCESS if life is good.
- *
- * Side Effects:
- *     A new ListNode is created and added to the list.
- *
- *-----------------------------------------------------------------------
- */
+/* Add a piece of data at the end of the given list. */
 ReturnStatus
 Lst_AtEnd(Lst l, void *d)
 {
@@ -471,19 +370,8 @@
  * Node-specific functions
  */
 
-/*-
- *-----------------------------------------------------------------------
- * Lst_First --
- *     Return the first node on the given list.
- *
- * Results:
- *     The first node or NULL if the list is empty.
- *
- * Side Effects:
- *     None.
- *
- *-----------------------------------------------------------------------
- */
+/* Return the first node from the given list, or NULL if the list is empty or
+ * invalid. */
 LstNode
 Lst_First(Lst l)
 {
@@ -494,19 +382,8 @@
     }
 }
 
-/*-
- *-----------------------------------------------------------------------
- * Lst_Last --
- *     Return the last node on the list l.
- *
- * Results:
- *     The requested node or NULL if the list is empty.
- *
- * Side Effects:
- *     None.
- *
- *-----------------------------------------------------------------------
- */
+/* Return the last node from the given list, or NULL if the list is empty or
+ * invalid. */
 LstNode
 Lst_Last(Lst l)
 {
@@ -539,19 +416,7 @@
     }
 }
 
-/*-
- *-----------------------------------------------------------------------
- * Lst_Datum --
- *     Return the datum stored in the given node.
- *
- * Results:
- *     The datum or NULL if the node is invalid.
- *
- * Side Effects:
- *     None.
- *
- *-----------------------------------------------------------------------
- */
+/* Return the datum stored in the given node, or NULL if the node is invalid. */
 void *
 Lst_Datum(LstNode ln)
 {
@@ -567,62 +432,24 @@
  * Functions for entire lists
  */
 
-/*-
- *-----------------------------------------------------------------------
- * Lst_IsEmpty --
- *     Return TRUE if the given list is empty.
- *
- * Results:
- *     TRUE if the list is empty, FALSE otherwise.
- *
- * Side Effects:
- *     None.
- *
- *     A list is considered empty if its firstPtr == NULL (or if
- *     the list itself is NULL).
- *-----------------------------------------------------------------------
- */
Prev by Date: [src/trunk]: src/sys Disable -Wshadow for libsodium.
Next by Date: [src/trunk]: src/sys Split flags onto separate lines, sorted, to make diffs e...
Previous by Thread: [src/trunk]: src/sys Disable -Wshadow for libsodium.
Next by Thread: [src/trunk]: src/sys Split flags onto separate lines, sorted, to make diffs e...
Indexes:
Home | Main Index | Thread Index | Old Index