Module Name: src Committed By: rillig Date: Fri Aug 21 06:28:38 UTC 2020
Modified Files: src/usr.bin/make: lst.c Log Message: 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. To generate a diff of this commit: cvs rdiff -u -r1.13 -r1.14 src/usr.bin/make/lst.c Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/usr.bin/make/lst.c diff -u src/usr.bin/make/lst.c:1.13 src/usr.bin/make/lst.c:1.14 --- src/usr.bin/make/lst.c:1.13 Fri Aug 21 05:28:41 2020 +++ src/usr.bin/make/lst.c Fri Aug 21 06:28:38 2020 @@ -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 @@ struct List { * 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 @@ LstNodeNew(void *datum) 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 @@ Lst_Init(void) 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 @@ Lst_Duplicate(Lst l, DuplicateProc *copy 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 @@ Lst_Destroy(Lst list, FreeProc *freeProc * 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 @@ Lst_InsertBefore(Lst l, LstNode ln, void 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 @@ Lst_InsertAfter(Lst l, LstNode ln, void 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 @@ Lst_AtFront(Lst l, void *d) 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 @@ Lst_ReplaceS(LstNode ln, void *d) * 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_First(Lst l) } } -/*- - *----------------------------------------------------------------------- - * 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_Prev(LstNode ln) } } -/*- - *----------------------------------------------------------------------- - * 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 @@ Lst_Datum(LstNode ln) * 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). - *----------------------------------------------------------------------- - */ +/* Return TRUE if the given list is empty or invalid. */ Boolean Lst_IsEmpty(Lst l) { return !LstValid(l) || LstIsEmpty(l); } -/*- - *----------------------------------------------------------------------- - * Lst_Find -- - * Find a node on the given list using the given comparison function - * and the given datum. - * - * Results: - * The found node or NULL if none matches. - * - * Side Effects: - * None. - * - *----------------------------------------------------------------------- - */ +/* Return the first node from the given list for which the given comparison + * function returns 0, or NULL if none of the nodes matches. */ LstNode Lst_Find(Lst l, const void *d, int (*cProc)(const void *, const void *)) { return Lst_FindFrom(l, Lst_First(l), d, cProc); } -/*- - *----------------------------------------------------------------------- - * Lst_FindFrom -- - * Search for a node starting and ending with the given one on the - * given list using the passed datum and comparison function to - * determine when it has been found. - * - * Results: - * The found node or NULL - * - * Side Effects: - * None. - * - *----------------------------------------------------------------------- - */ +/* Return the first node from the given list, starting at the given node, for + * which the given comparison function returns 0, or NULL if none of the nodes + * matches. */ LstNode Lst_FindFrom(Lst l, LstNode ln, const void *d, int (*cProc)(const void *, const void *)) @@ -644,9 +471,7 @@ Lst_FindFrom(Lst l, LstNode ln, const vo return NULL; } -/*- - * See if a given datum is on a given list. - */ +/* Return the first node that contains the given datum, or NULL. */ LstNode Lst_Member(Lst l, void *d) { @@ -671,46 +496,18 @@ Lst_Member(Lst l, void *d) return NULL; } -/*- - *----------------------------------------------------------------------- - * Lst_ForEach -- - * Apply the given function to each element of the given list. The - * function should return 0 if Lst_ForEach should continue and non- - * zero if it should abort. - * - * Results: - * None. - * - * Side Effects: - * Only those created by the passed-in function. - * - *----------------------------------------------------------------------- - */ -/*VARARGS2*/ +/* Apply the given function to each element of the given list. The function + * should return 0 if traversal should continue and non-zero if it should + * abort. */ int Lst_ForEach(Lst l, int (*proc)(void *, void *), void *d) { return Lst_ForEachFrom(l, Lst_First(l), proc, d); } -/*- - *----------------------------------------------------------------------- - * Lst_ForEachFrom -- - * Apply the given function to each element of the given list, - * starting from a given point. - * - * The function should return 0 if traversal should continue, and - * non-zero if it should abort. - * - * Results: - * None. - * - * Side Effects: - * Only those created by the passed-in function. - * - *----------------------------------------------------------------------- - */ -/*VARARGS2*/ +/* Apply the given function to each element of the given list, starting from + * the given node. The function should return 0 if traversal should continue, + * and non-zero if it should abort. */ int Lst_ForEachFrom(Lst l, LstNode ln, int (*proc)(void *, void *), void *d) @@ -765,28 +562,18 @@ Lst_ForEachFrom(Lst l, LstNode ln, int ( return result; } -/*- - *----------------------------------------------------------------------- - * Lst_Concat -- - * Concatenate two lists. New elements are created to hold the data - * elements, if specified, but the elements themselves are not copied. - * If the elements should be duplicated to avoid confusion with another - * list, the Lst_Duplicate function should be called first. - * If LST_CONCLINK is specified, the second list is destroyed since - * its pointers have been corrupted and the list is no longer useable. +/* Concatenate two lists. New nodes are created to hold the data elements, + * if specified, but the data themselves are not copied. If the data + * should be duplicated to avoid confusion with another list, the Lst_Duplicate + * function should be called first. If LST_CONCLINK is specified, the second + * list is destroyed since its pointers have been corrupted and the list is no + * longer usable. * * Input: * l1 The list to which l2 is to be appended * l2 The list to append to l1 - * flags LST_CONCNEW if LstNode's should be duplicated - * LST_CONCLINK if should just be relinked - * - * Results: - * SUCCESS if all went well. FAILURE otherwise. - * - * Side Effects: - * New elements are created and appended the first list. - *----------------------------------------------------------------------- + * flags LST_CONCNEW if the list nodes should be duplicated + * LST_CONCLINK if the list nodes should just be relinked */ ReturnStatus Lst_Concat(Lst l1, Lst l2, int flags) @@ -871,22 +658,8 @@ Lst_Concat(Lst l1, Lst l2, int flags) * access the list based on it. */ -/*- - *----------------------------------------------------------------------- - * Lst_Open -- - * Open a list for sequential access. A list can still be searched, - * etc., without confusing these functions. - * - * Results: - * SUCCESS or FAILURE. - * - * Side Effects: - * isOpen is set TRUE and curPtr is set to NULL so the - * other sequential functions know it was just opened and can choose - * the first element accessed based on this. - * - *----------------------------------------------------------------------- - */ +/* Open a list for sequential access. A list can still be searched, etc., + * without confusing these functions. */ ReturnStatus Lst_Open(Lst l) { @@ -976,20 +749,7 @@ Lst_CloseS(Lst l) * for using the list as a queue */ -/*- - *----------------------------------------------------------------------- - * Lst_EnQueue -- - * Add the datum to the tail of the given list. - * - * Results: - * SUCCESS or FAILURE as returned by Lst_InsertAfter. - * - * Side Effects: - * the lastPtr field is altered all the time and the firstPtr field - * will be altered if the list used to be empty. - * - *----------------------------------------------------------------------- - */ +/* Add the datum to the tail of the given list. */ ReturnStatus Lst_EnQueue(Lst l, void *d) { @@ -1000,20 +760,8 @@ Lst_EnQueue(Lst l, void *d) return Lst_InsertAfter(l, Lst_Last(l), d); } -/*- - *----------------------------------------------------------------------- - * Lst_DeQueue -- - * Remove and return the datum at the head of the given list. - * - * Results: - * The datum in the node at the head or NULL if the list - * is empty. - * - * Side Effects: - * The head node is removed from the list. - * - *----------------------------------------------------------------------- - */ +/* Remove and return the datum at the head of the given list, or NULL if the + * list is empty. */ void * Lst_DeQueue(Lst l) {