[src/trunk]: src/usr.bin/make make(1): improve documentation for enum.c and e...

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

details:   https://anonhg.NetBSD.org/src/rev/00589fa1b65a
branches:  trunk
changeset: 943381:00589fa1b65a
user:      rillig <rillig%NetBSD.org@localhost>
date:      Tue Sep 01 20:34:51 2020 +0000

description:
make(1): improve documentation for enum.c and enum.h

diffstat:

 usr.bin/make/enum.c |  15 ++++++++++-----
 usr.bin/make/enum.h |   6 ++----
 2 files changed, 12 insertions(+), 9 deletions(-)

diffs (66 lines):

diff -r e5d3fbd199bf -r 00589fa1b65a usr.bin/make/enum.c
--- a/usr.bin/make/enum.c       Tue Sep 01 20:17:18 2020 +0000
+++ b/usr.bin/make/enum.c       Tue Sep 01 20:34:51 2020 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: enum.c,v 1.5 2020/08/28 19:46:04 rillig Exp $  */
+/*     $NetBSD: enum.c,v 1.6 2020/09/01 20:34:51 rillig Exp $  */
 
 /*
  Copyright (c) 2020 Roland Illig <rillig%NetBSD.org@localhost>
@@ -28,11 +28,11 @@
  */
 
 #ifndef MAKE_NATIVE
-static char rcsid[] = "$NetBSD: enum.c,v 1.5 2020/08/28 19:46:04 rillig Exp $";
+static char rcsid[] = "$NetBSD: enum.c,v 1.6 2020/09/01 20:34:51 rillig Exp $";
 #else
 #include <sys/cdefs.h>
 #ifndef lint
-__RCSID("$NetBSD: enum.c,v 1.5 2020/08/28 19:46:04 rillig Exp $");
+__RCSID("$NetBSD: enum.c,v 1.6 2020/09/01 20:34:51 rillig Exp $");
 #endif
 #endif
 
@@ -42,8 +42,11 @@
 
 #include "enum.h"
 
-/* Convert a bitset into a string representation showing the names of the
- * individual bits, or optionally shortcuts for groups of bits. */
+/* Convert a bitset into a string representation, showing the names of the
+ * individual bits.
+ *
+ * Optionally, shortcuts for groups of bits can be added.  To have an effect,
+ * they need to be listed before their individual bits. */
 const char *
 Enum_FlagsToString(char *buf, size_t buf_size,
                   int value, const EnumToStringSpec *spec)
@@ -73,6 +76,8 @@
                sep = ENUM__SEP;
                sep_len = sizeof ENUM__SEP - 1;
        }
+
+       /* If this assertion fails, the listed enum values are incomplete. */
        assert(value == 0);
 
        if (buf == buf_start)
diff -r e5d3fbd199bf -r 00589fa1b65a usr.bin/make/enum.h
--- a/usr.bin/make/enum.h       Tue Sep 01 20:17:18 2020 +0000
+++ b/usr.bin/make/enum.h       Tue Sep 01 20:34:51 2020 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: enum.h,v 1.8 2020/08/25 16:27:24 rillig Exp $  */
+/*     $NetBSD: enum.h,v 1.9 2020/09/01 20:34:51 rillig Exp $  */
 
 /*
  Copyright (c) 2020 Roland Illig <rillig%NetBSD.org@localhost>
@@ -30,9 +30,7 @@
 #ifndef MAKE_ENUM_H
 #define MAKE_ENUM_H
 
-/*
- * Generate string representation for bitmasks.
- */
+/* Generate string representations for bitmasks and simple enums. */
 
 #include <stddef.h>