[src/trunk]: src/usr.bin/make make(1): fix documentation of Var_Parse

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

details:   https://anonhg.NetBSD.org/src/rev/388fa71f64ed
branches:  trunk
changeset: 975159:388fa71f64ed
user:      rillig <rillig%NetBSD.org@localhost>
date:      Sat Aug 22 17:32:55 2020 +0000

description:
make(1): fix documentation of Var_Parse

diffstat:

 usr.bin/make/var.c |  26 +++++++++++---------------
 1 files changed, 11 insertions(+), 15 deletions(-)

diffs (60 lines):

diff -r 5340bd8cdcd7 -r 388fa71f64ed usr.bin/make/var.c
--- a/usr.bin/make/var.c        Sat Aug 22 16:51:25 2020 +0000
+++ b/usr.bin/make/var.c        Sat Aug 22 17:32:55 2020 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: var.c,v 1.454 2020/08/20 07:15:52 rillig Exp $ */
+/*     $NetBSD: var.c,v 1.455 2020/08/22 17:32:55 rillig Exp $ */
 
 /*
  * Copyright (c) 1988, 1989, 1990, 1993
@@ -69,14 +69,14 @@
  */
 
 #ifndef MAKE_NATIVE
-static char rcsid[] = "$NetBSD: var.c,v 1.454 2020/08/20 07:15:52 rillig Exp $";
+static char rcsid[] = "$NetBSD: var.c,v 1.455 2020/08/22 17:32:55 rillig Exp $";
 #else
 #include <sys/cdefs.h>
 #ifndef lint
 #if 0
 static char sccsid[] = "@(#)var.c      8.3 (Berkeley) 3/19/94";
 #else
-__RCSID("$NetBSD: var.c,v 1.454 2020/08/20 07:15:52 rillig Exp $");
+__RCSID("$NetBSD: var.c,v 1.455 2020/08/22 17:32:55 rillig Exp $");
 #endif
 #endif /* not lint */
 #endif
@@ -3323,12 +3323,14 @@
  *     freePtr         OUT: Non-NULL if caller should free *freePtr
  *
  * Results:
- *     The value of the variable expression or var_Error if the
- *     specification is invalid. The length of the specification is
- *     placed in *lengthPtr (for invalid specifications, this is just
- *     2...?).
- *     If *freePtr is non-NULL then it's a pointer that the caller
- *     should pass to free() to free memory used by the result.
+ *     Returns the value of the variable expression.
+ *     var_Error if there was a parse error and VARE_UNDEFERR was set.
+ *     varNoError if there was a parse error and VARE_UNDEFERR was not set.
+ *
+ *     Parsing should continue at str + *lengthPtr.
+ *
+ *     After using the returned value, *freePtr must be freed, preferably
+ *     using bmake_free since it is NULL in most cases.
  *
  * Side Effects:
  *     Any effects from the modifiers, such as :!cmd! or ::=value.
@@ -3686,12 +3688,6 @@
            void *freeIt;
            const char *val = Var_Parse(str, ctxt, eflags, &length, &freeIt);
 
-           /*
-            * When we come down here, val should either point to the
-            * value of this variable, suitably modified, or be NULL.
-            * Length should be the total length of the potential
-            * variable invocation (from $ to end character...)
-            */
            if (val == var_Error || val == varNoError) {
                /*
                 * If performing old-time variable substitution, skip over