[src/trunk]: src/usr.bin/make make(1): remove redundant documentation from co...

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

details:   https://anonhg.NetBSD.org/src/rev/2db315b96705
branches:  trunk
changeset: 974681:2db315b96705
user:      rillig <rillig%NetBSD.org@localhost>
date:      Sat Aug 08 16:57:59 2020 +0000

description:
make(1): remove redundant documentation from cond.c

Many of the functions in cond.c are so small that it's faster to read
their code instead of a large block of documentation.

There are other functions that actually need a detailed description.
These have been left as-is.

diffstat:

 usr.bin/make/cond.c |  209 ++++++++++-----------------------------------------
 1 files changed, 41 insertions(+), 168 deletions(-)

diffs (truncated from 347 to 300 lines):

diff -r d289d850c68b -r 2db315b96705 usr.bin/make/cond.c
--- a/usr.bin/make/cond.c       Sat Aug 08 16:31:37 2020 +0000
+++ b/usr.bin/make/cond.c       Sat Aug 08 16:57:59 2020 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: cond.c,v 1.89 2020/08/08 16:31:37 rillig Exp $ */
+/*     $NetBSD: cond.c,v 1.90 2020/08/08 16:57:59 rillig Exp $ */
 
 /*
  * Copyright (c) 1988, 1989, 1990 The Regents of the University of California.
@@ -70,14 +70,14 @@
  */
 
 #ifndef MAKE_NATIVE
-static char rcsid[] = "$NetBSD: cond.c,v 1.89 2020/08/08 16:31:37 rillig Exp $";
+static char rcsid[] = "$NetBSD: cond.c,v 1.90 2020/08/08 16:57:59 rillig Exp $";
 #else
 #include <sys/cdefs.h>
 #ifndef lint
 #if 0
 static char sccsid[] = "@(#)cond.c     8.2 (Berkeley) 1/2/94";
 #else
-__RCSID("$NetBSD: cond.c,v 1.89 2020/08/08 16:31:37 rillig Exp $");
+__RCSID("$NetBSD: cond.c,v 1.90 2020/08/08 16:57:59 rillig Exp $");
 #endif
 #endif /* not lint */
 #endif
@@ -171,42 +171,21 @@
        return strncmp(str, tok, len) == 0 && !isalpha((unsigned char)str[len]);
 }
 
-/*-
- *-----------------------------------------------------------------------
- * CondPushBack --
- *     Push back the most recent token read. We only need one level of
- *     this, so the thing is just stored in 'condPushback'.
- *
- * Input:
- *     t               Token to push back into the "stream"
- *
- * Results:
- *     None.
- *
- * Side Effects:
- *     condPushback is overwritten.
- *
- *-----------------------------------------------------------------------
- */
+/* Push back the most recent token read. We only need one level of
+ * this, so the thing is just stored in 'condPushback'. */
 static void
 CondPushBack(Token t)
 {
     condPushBack = t;
 }
-
+
 /*-
- *-----------------------------------------------------------------------
- * CondGetArg --
- *     Find the argument of a built-in function.
+ * Parse the argument of a built-in function.
  *
  * Results:
- *     The length of the argument and the address of the argument.
- *
- * Side Effects:
- *     The pointer is set to point to the closing parenthesis of the
- *     function call.
- *
- *-----------------------------------------------------------------------
+ *     The length of the argument.
+ *     *argPtr receives the argument as string.
+ *     *linePtr is updated to point behind the ')' of the function call.
  */
 static int
 CondGetArg(Boolean doEval, char **linePtr, char **argPtr, const char *func)
@@ -291,20 +270,8 @@
     *linePtr = cp;
     return argLen;
 }
-
-/*-
- *-----------------------------------------------------------------------
- * CondDoDefined --
- *     Handle the 'defined' function for conditionals.
- *
- * Results:
- *     TRUE if the given variable is defined.
- *
- * Side Effects:
- *     None.
- *
- *-----------------------------------------------------------------------
- */
+
+/* Test whether the given variable is defined. */
 static Boolean
 CondDoDefined(int argLen MAKE_ATTR_UNUSED, const char *arg)
 {
@@ -313,59 +280,23 @@
     bmake_free(freeIt);
     return result;
 }
-
-/*-
- *-----------------------------------------------------------------------
- * CondStrMatch --
- *     Front-end for Str_Match so it returns 0 on match and non-zero
- *     on mismatch. Callback function for CondDoMake via Lst_Find
- *
- * Results:
- *     0 if string matches pattern
- *
- * Side Effects:
- *     None
- *
- *-----------------------------------------------------------------------
- */
+
+/* Wrapper around Str_Match that returns 0 on match and non-zero
+ * on mismatch. Callback function for CondDoMake via Lst_Find. */
 static int
-CondStrMatch(const void *string, const void *pattern)
+CondFindStrMatch(const void *string, const void *pattern)
 {
     return !Str_Match(string, pattern);
 }
-
-/*-
- *-----------------------------------------------------------------------
- * CondDoMake --
- *     Handle the 'make' function for conditionals.
- *
- * Results:
- *     TRUE if the given target is being made.
- *
- * Side Effects:
- *     None.
- *
- *-----------------------------------------------------------------------
- */
+
+/* See if the given target is being made. */
 static Boolean
 CondDoMake(int argLen MAKE_ATTR_UNUSED, const char *arg)
 {
-    return Lst_Find(create, arg, CondStrMatch) != NULL;
+    return Lst_Find(create, arg, CondFindStrMatch) != NULL;
 }
-
-/*-
- *-----------------------------------------------------------------------
- * CondDoExists --
- *     See if the given file exists.
- *
- * Results:
- *     TRUE if the file exists and FALSE if it does not.
- *
- * Side Effects:
- *     None.
- *
- *-----------------------------------------------------------------------
- */
+
+/* See if the given file exists. */
 static Boolean
 CondDoExists(int argLen MAKE_ATTR_UNUSED, const char *arg)
 {
@@ -385,20 +316,8 @@
     }
     return result;
 }
-
-/*-
- *-----------------------------------------------------------------------
- * CondDoTarget --
- *     See if the given node exists and is an actual target.
- *
- * Results:
- *     TRUE if the node exists as a target and FALSE if it does not.
- *
- * Side Effects:
- *     None.
- *
- *-----------------------------------------------------------------------
- */
+
+/* See if the given node exists and is an actual target. */
 static Boolean
 CondDoTarget(int argLen MAKE_ATTR_UNUSED, const char *arg)
 {
@@ -408,21 +327,8 @@
     return gn != NULL && !OP_NOP(gn->type);
 }
 
-/*-
- *-----------------------------------------------------------------------
- * CondDoCommands --
- *     See if the given node exists and is an actual target with commands
- *     associated with it.
- *
- * Results:
- *     TRUE if the node exists as a target and has commands associated with
- *     it and FALSE if it does not.
- *
- * Side Effects:
- *     None.
- *
- *-----------------------------------------------------------------------
- */
+/* See if the given node exists and is an actual target with commands
+ * associated with it. */
 static Boolean
 CondDoCommands(int argLen MAKE_ATTR_UNUSED, const char *arg)
 {
@@ -431,19 +337,15 @@
     gn = Targ_FindNode(arg, TARG_NOCREATE);
     return gn != NULL && !OP_NOP(gn->type) && !Lst_IsEmpty(gn->commands);
 }
-
+
 /*-
- *-----------------------------------------------------------------------
- * CondCvtArg --
- *     Convert the given number into a double.
- *     We try a base 10 or 16 integer conversion first, if that fails
- *     then we try a floating point conversion instead.
+ * Convert the given number into a double.
+ * We try a base 10 or 16 integer conversion first, if that fails
+ * then we try a floating point conversion instead.
  *
  * Results:
  *     Sets 'value' to double value of string.
- *     Returns 'true' if the convertion suceeded
- *
- *-----------------------------------------------------------------------
+ *     Returns TRUE if the conversion succeeded.
  */
 static Boolean
 CondCvtArg(const char *str, double *value)
@@ -474,22 +376,16 @@
 }
 
 /*-
- *-----------------------------------------------------------------------
- * CondGetString --
- *     Get a string from a variable reference or an optionally quoted
- *     string.  This is called for the lhs and rhs of string compares.
+ * Get a string from a variable reference or an optionally quoted
+ * string.  This is called for the lhs and rhs of string compares.
  *
  * Results:
- *     Sets freeIt if needed,
- *     Sets quoted if string was quoted,
- *     Returns NULL on error,
- *     else returns string - absent any quotes.
+ *     Returns the string, absent any quotes, or NULL on error.
+ *     Sets quoted if the string was quoted.
+ *     Sets freeIt if needed.
  *
  * Side Effects:
- *     Moves condExpr to end of this token.
- *
- *
- *-----------------------------------------------------------------------
+ *     Moves condExpr past the end of this token.
  */
 /* coverity:[+alloc : arg-*2] */
 static const char *
@@ -615,17 +511,10 @@
 };
 
 /*-
- *-----------------------------------------------------------------------
- * CondToken --
- *     Return the next token from the input.
- *
- * Results:
- *     A Token for the next lexical token in the stream.
+ * Return the next token from the input.
  *
  * Side Effects:
  *     condPushback will be set back to TOK_NONE if it is used.
- *
- *-----------------------------------------------------------------------
  */
 static Token
 compare_expression(Boolean doEval)
@@ -1023,7 +912,7 @@
     }
     return t;
 }
-
+
 /*-
  *-----------------------------------------------------------------------
  * CondF --
@@ -1069,7 +958,7 @@
     }
     return l;