From: mdw <mdw>
Date: Fri, 22 Oct 1999 22:46:44 +0000 (+0000)
Subject: Improve documentation for conf_enum.
X-Git-Tag: 1.2.0~4
X-Git-Url: https://git.distorted.org.uk/~mdw/fwd/commitdiff_plain/827937594af083b860203b9872d7171033954dee

Improve documentation for conf_enum.
---

diff --git a/conf.c b/conf.c
index 39d170d..3211db1 100644
--- a/conf.c
+++ b/conf.c
@@ -1,6 +1,6 @@
 /* -*-c-*-
  *
- * $Id: conf.c,v 1.4 1999/10/15 21:12:36 mdw Exp $
+ * $Id: conf.c,v 1.5 1999/10/22 22:46:44 mdw Exp $
  *
  * Configuration parsing
  *
@@ -29,6 +29,9 @@
 /*----- Revision history --------------------------------------------------* 
  *
  * $Log: conf.c,v $
+ * Revision 1.5  1999/10/22 22:46:44  mdw
+ * Improve documentation for conf_enum.
+ *
  * Revision 1.4  1999/10/15 21:12:36  mdw
  * Remove redundant debugging code.
  *
@@ -247,9 +250,15 @@ void error(scanner *sc, const char *msg, ...)
  * Returns:	Index into list, zero-based, or @-1@.
  *
  * Use:		Checks whether the current token is a string which matches
- *		one of the comma-separated items given.  If not, an error is
- *		reported; otherwise the index of the matched item is
- *		returned.
+ *		one of the comma-separated items given.  The return value is
+ *		the index (zero-based) of the matched string in the list.
+ *
+ *		The flags control the behaviour if no exact match is found.
+ *		If @ENUM_ABBREV@ is set, and the current token is a left
+ *		substring of exactly one of the possibilities, then that one
+ *		is chosen.  If @ENUM_NONE@ is set, the value @-1@ is
+ *		returned; otherwise an error is reported and the program is
+ *		terminated.
  */
 
 int conf_enum(scanner *sc, const char *list, unsigned f, const char *err)
diff --git a/conf.h b/conf.h
index e0eddf8..5b78b13 100644
--- a/conf.h
+++ b/conf.h
@@ -1,6 +1,6 @@
 /* -*-c-*-
  *
- * $Id: conf.h,v 1.4 1999/08/19 18:32:48 mdw Exp $
+ * $Id: conf.h,v 1.5 1999/10/22 22:46:44 mdw Exp $
  *
  * Configuration parsing
  *
@@ -29,6 +29,9 @@
 /*----- Revision history --------------------------------------------------* 
  *
  * $Log: conf.h,v $
+ * Revision 1.5  1999/10/22 22:46:44  mdw
+ * Improve documentation for conf_enum.
+ *
  * Revision 1.4  1999/08/19 18:32:48  mdw
  * Improve lexical analysis.  In particular, `chmod' patterns don't have to
  * be quoted any more.
@@ -114,9 +117,15 @@ extern void error(scanner */*sc*/, const char */*msg*/, ...);
  * Returns:	Index into list, zero-based, or @-1@.
  *
  * Use:		Checks whether the current token is a string which matches
- *		one of the comma-separated items given.  If not, an error is
- *		reported; otherwise the index of the matched item is
- *		returned.
+ *		one of the comma-separated items given.  The return value is
+ *		the index (zero-based) of the matched string in the list.
+ *
+ *		The flags control the behaviour if no exact match is found.
+ *		If @ENUM_ABBREV@ is set, and the current token is a left
+ *		substring of exactly one of the possibilities, then that one
+ *		is chosen.  If @ENUM_NONE@ is set, the value @-1@ is
+ *		returned; otherwise an error is reported and the program is
+ *		terminated.
  */
 
 #define ENUM_ABBREV 1u