From: Mark Andrews <marka@isc.org>
Date: Wed, 9 Sep 2015 07:02:11 +0000 (+1000)
Subject: 4196.   [doc]           Improve how "enum + other" types are documented.
X-Git-Tag: v9.11.0a1~502^2~10
X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=4ca7391e640bd4f0abb31508019d3bd62819fa8e;p=thirdparty%2Fbind9.git

4196.   [doc]           Improve how "enum + other" types are documented.
                        [RT #40608]

4195.   [bug]           'max-zone-ttl unlimited;' was broken. [RT #40608]
---

diff --git a/CHANGES b/CHANGES
index 5769b16166c..954f9ae55dc 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,3 +1,8 @@
+4196.	[doc]		Improve how "enum + other" types are documented.
+			[RT #40608]
+
+4195.	[bug]		'max-zone-ttl unlimited;' was broken. [RT #40608]
+
 4194.	[bug]		named-checkconf -p failed to properly print a port
 			range.  [RT #40634]
 
diff --git a/bin/named/zoneconf.c b/bin/named/zoneconf.c
index 7592e6d440d..e46c52e1c7f 100644
--- a/bin/named/zoneconf.c
+++ b/bin/named/zoneconf.c
@@ -991,7 +991,10 @@ ns_zone_configure(const cfg_obj_t *config, const cfg_obj_t *vconfig,
 			      "with 'masterfile-format map'", zname);
 		return (ISC_R_FAILURE);
 	} else if (result == ISC_R_SUCCESS) {
-		dns_ttl_t maxttl = cfg_obj_asuint32(obj);
+		dns_ttl_t maxttl = 0;	/* unlimited */
+
+		if (cfg_obj_isuint32(obj))
+			maxttl = cfg_obj_asuint32(obj);
 		dns_zone_setmaxttl(zone, maxttl);
 		if (raw != NULL)
 			dns_zone_setmaxttl(raw, maxttl);
diff --git a/bin/tests/system/resolver/ns1/named.conf b/bin/tests/system/resolver/ns1/named.conf
index 96f4aa1923d..4fe510c064f 100644
--- a/bin/tests/system/resolver/ns1/named.conf
+++ b/bin/tests/system/resolver/ns1/named.conf
@@ -35,6 +35,7 @@ options {
 		except-from { "goodcname.example.net";
 			      "gooddname.example.net"; };
 	allow-query {!10.53.0.8; any; };
+	max-zone-ttl unlimited;
 };
 
 server 10.42.23.3/32 {
diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml
index eb56c97152f..dd5c65640a8 100644
--- a/doc/arm/Bv9ARM-book.xml
+++ b/doc/arm/Bv9ARM-book.xml
@@ -4932,7 +4932,7 @@ badresp:1,adberr:0,findfail:0,valfail:0]
     <optional> lame-ttl <replaceable>number</replaceable>; </optional>
     <optional> max-ncache-ttl <replaceable>number</replaceable>; </optional>
     <optional> max-cache-ttl <replaceable>number</replaceable>; </optional>
-    <optional> max-zone-ttl <replaceable>number</replaceable> ; </optional>
+    <optional> max-zone-ttl ( <constant>unlimited</constant> | <replaceable>number</replaceable> ; </optional>
     <optional> servfail-ttl <replaceable>number</replaceable>; </optional>
     <optional> sig-validity-interval <replaceable>number</replaceable> <optional><replaceable>number</replaceable></optional> ; </optional>
     <optional> sig-signing-nodes <replaceable>number</replaceable> ; </optional>
@@ -5913,6 +5913,11 @@ options {
 		load directly into memory, this option cannot be
 		used with them.)
 	      </para>
+	      <para>
+		The default value is <constant>unlimited</constant>.
+		A <option>max-zone-ttl</option> of zero is treated as
+		<constant>unlimited</constant>.
+	      </para>
 	    </listitem>
 	  </varlistentry>
 
diff --git a/doc/misc/options b/doc/misc/options
index 26e409e975a..b661ecf023f 100644
--- a/doc/misc/options
+++ b/doc/misc/options
@@ -101,14 +101,14 @@ options {
         clients-per-query <integer>;
         cookie-algorithm ( aes | sha1 | sha256 );
         cookie-secret <string>;
-        coresize <size>;
-        datasize <size>;
+        coresize ( unlimited | default | <sizeval> );
+        datasize ( unlimited | default | <sizeval> );
         deallocate-on-exit <boolean>; // obsolete
         deny-answer-addresses { <address_match_element>; ... } [
             except-from { <quoted_string>; ... } ];
         deny-answer-aliases { <quoted_string>; ... } [ except-from {
             <quoted_string>; ... } ];
-        dialup <dialuptype>;
+        dialup ( notify | notify-passive | refresh | passive | <boolean> );
         directory <quoted_string>;
         disable-algorithms <string> { <string>; ... };
         disable-ds-digests <string> { <string>; ... };
@@ -147,10 +147,10 @@ options {
         fetch-quota-params <integer> <fixedpoint> <fixedpoint> <fixedpoint>;
         fetches-per-server <integer> [ ( drop | fail ) ];
         fetches-per-zone <integer> [ ( drop | fail ) ];
-        files <size>;
+        files ( unlimited | default | <sizeval> );
         filter-aaaa { <address_match_element>; ... }; // not configured
-        filter-aaaa-on-v4 <filter_aaaa>; // not configured
-        filter-aaaa-on-v6 <filter_aaaa>; // not configured
+        filter-aaaa-on-v4 ( break-dnssec | <boolean> ); // not configured
+        filter-aaaa-on-v6 ( break-dnssec | <boolean> ); // not configured
         flush-zones-on-shutdown <boolean>;
         forward ( first | only );
         forwarders [ port <integer> ] [ dscp <integer> ] { ( <ipv4_address>
@@ -164,7 +164,7 @@ options {
         hostname ( <quoted_string> | none );
         inline-signing <boolean>;
         interface-interval <integer>;
-        ixfr-from-differences <ixfrdiff>;
+        ixfr-from-differences ( master | slave | <boolean> );
         keep-response-order { <address_match_element>; ... };
         key-directory <quoted_string>;
         lame-ttl <ttlval>;
@@ -182,7 +182,7 @@ options {
         max-cache-size <size_no_default>;
         max-cache-ttl <integer>;
         max-clients-per-query <integer>;
-        max-ixfr-log-size <size>; // obsolete
+        max-ixfr-log-size ( unlimited | default | <sizeval> ); // obsolete
         max-journal-size <size_no_default>;
         max-ncache-ttl <integer>;
         max-recursion-depth <integer>;
@@ -195,7 +195,7 @@ options {
         max-transfer-time-in <integer>;
         max-transfer-time-out <integer>;
         max-udp-size <integer>;
-        max-zone-ttl <maxttl_no_default>;
+        max-zone-ttl ( unlimited | <ttlval> );
         memstatistics <boolean>;
         memstatistics-file <quoted_string>;
         min-refresh-time <integer>;
@@ -208,7 +208,7 @@ options {
         no-case-compress { <address_match_element>; ... };
         nocookie-udp-size <integer>;
         nosit-udp-size <integer>; // obsolete
-        notify <notifytype>;
+        notify ( explicit | master-only | <boolean> );
         notify-delay <integer>;
         notify-rate <integer>;
         notify-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [
@@ -285,7 +285,7 @@ options {
         sig-validity-interval <integer> [ <integer> ];
         sit-secret <string>; // obsolete
         sortlist { <address_match_element>; ... };
-        stacksize <size>;
+        stacksize ( unlimited | default | <sizeval> );
         startup-notify-rate <integer>;
         statistics-file <quoted_string>;
         statistics-interval <integer>; // not yet implemented
@@ -317,7 +317,7 @@ options {
         version ( <quoted_string> | none );
         zero-no-soa-ttl <boolean>;
         zero-no-soa-ttl-cache <boolean>;
-        zone-statistics <zonestat>;
+        zone-statistics ( full | terse | none | <boolean> );
 };
 
 server <netprefix> {
@@ -399,7 +399,7 @@ view <string> <optional_class> {
             except-from { <quoted_string>; ... } ];
         deny-answer-aliases { <quoted_string>; ... } [ except-from {
             <quoted_string>; ... } ];
-        dialup <dialuptype>;
+        dialup ( notify | notify-passive | refresh | passive | <boolean> );
         disable-algorithms <string> { <string>; ... };
         disable-ds-digests <string> { <string>; ... };
         disable-empty-zone <string>;
@@ -439,13 +439,13 @@ view <string> <optional_class> {
         fetches-per-server <integer> [ ( drop | fail ) ];
         fetches-per-zone <integer> [ ( drop | fail ) ];
         filter-aaaa { <address_match_element>; ... }; // not configured
-        filter-aaaa-on-v4 <filter_aaaa>; // not configured
-        filter-aaaa-on-v6 <filter_aaaa>; // not configured
+        filter-aaaa-on-v4 ( break-dnssec | <boolean> ); // not configured
+        filter-aaaa-on-v6 ( break-dnssec | <boolean> ); // not configured
         forward ( first | only );
         forwarders [ port <integer> ] [ dscp <integer> ] { ( <ipv4_address>
             | <ipv6_address> ) [ port <integer> ] [ dscp <integer> ]; ... };
         inline-signing <boolean>;
-        ixfr-from-differences <ixfrdiff>;
+        ixfr-from-differences ( master | slave | <boolean> );
         key <string> {
                 algorithm <string>;
                 secret <string>;
@@ -464,7 +464,7 @@ view <string> <optional_class> {
         max-cache-size <size_no_default>;
         max-cache-ttl <integer>;
         max-clients-per-query <integer>;
-        max-ixfr-log-size <size>; // obsolete
+        max-ixfr-log-size ( unlimited | default | <sizeval> ); // obsolete
         max-journal-size <size_no_default>;
         max-ncache-ttl <integer>;
         max-recursion-depth <integer>;
@@ -476,7 +476,7 @@ view <string> <optional_class> {
         max-transfer-time-in <integer>;
         max-transfer-time-out <integer>;
         max-udp-size <integer>;
-        max-zone-ttl <maxttl_no_default>;
+        max-zone-ttl ( unlimited | <ttlval> );
         min-refresh-time <integer>;
         min-retry-time <integer>;
         min-roots <integer>; // not implemented
@@ -485,7 +485,7 @@ view <string> <optional_class> {
         no-case-compress { <address_match_element>; ... };
         nocookie-udp-size <integer>;
         nosit-udp-size <integer>; // obsolete
-        notify <notifytype>;
+        notify ( explicit | master-only | <boolean> );
         notify-delay <integer>;
         notify-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [
             dscp <integer> ];
@@ -616,7 +616,8 @@ view <string> <optional_class> {
                 check-wildcard <boolean>;
                 database <string>;
                 delegation-only <boolean>;
-                dialup <dialuptype>;
+                dialup ( notify | notify-passive | refresh | passive |
+                    <boolean> );
                 dlz <string>;
                 dnssec-dnskey-kskonly <boolean>;
                 dnssec-loadkeys-interval <integer>;
@@ -640,7 +641,8 @@ view <string> <optional_class> {
                 masters [ port <integer> ] [ dscp <integer> ] { ( <masters>
                     | <ipv4_address> [ port <integer> ] | <ipv6_address> [
                     port <integer> ] ) [ key <string> ]; ... };
-                max-ixfr-log-size <size>; // obsolete
+                max-ixfr-log-size ( unlimited | default |
+                    <sizeval> ); // obsolete
                 max-journal-size <size_no_default>;
                 max-refresh-time <integer>;
                 max-retry-time <integer>;
@@ -648,11 +650,11 @@ view <string> <optional_class> {
                 max-transfer-idle-out <integer>;
                 max-transfer-time-in <integer>;
                 max-transfer-time-out <integer>;
-                max-zone-ttl <maxttl_no_default>;
+                max-zone-ttl ( unlimited | <ttlval> );
                 min-refresh-time <integer>;
                 min-retry-time <integer>;
                 multi-master <boolean>;
-                notify <notifytype>;
+                notify ( explicit | master-only | <boolean> );
                 notify-delay <integer>;
                 notify-source ( <ipv4_address> | * ) [ port ( <integer> | *
                     ) ] [ dscp <integer> ];
@@ -687,9 +689,9 @@ view <string> <optional_class> {
                     ] <rrtypelist>; ... };
                 use-alt-transfer-source <boolean>;
                 zero-no-soa-ttl <boolean>;
-                zone-statistics <zonestat>;
+                zone-statistics ( full | terse | none | <boolean> );
         };
-        zone-statistics <zonestat>;
+        zone-statistics ( full | terse | none | <boolean> );
 };
 
 zone <string> <optional_class> {
@@ -718,7 +720,7 @@ zone <string> <optional_class> {
         check-wildcard <boolean>;
         database <string>;
         delegation-only <boolean>;
-        dialup <dialuptype>;
+        dialup ( notify | notify-passive | refresh | passive | <boolean> );
         dlz <string>;
         dnssec-dnskey-kskonly <boolean>;
         dnssec-loadkeys-interval <integer>;
@@ -741,7 +743,7 @@ zone <string> <optional_class> {
         masters [ port <integer> ] [ dscp <integer> ] { ( <masters> |
             <ipv4_address> [ port <integer> ] | <ipv6_address> [ port
             <integer> ] ) [ key <string> ]; ... };
-        max-ixfr-log-size <size>; // obsolete
+        max-ixfr-log-size ( unlimited | default | <sizeval> ); // obsolete
         max-journal-size <size_no_default>;
         max-refresh-time <integer>;
         max-retry-time <integer>;
@@ -749,11 +751,11 @@ zone <string> <optional_class> {
         max-transfer-idle-out <integer>;
         max-transfer-time-in <integer>;
         max-transfer-time-out <integer>;
-        max-zone-ttl <maxttl_no_default>;
+        max-zone-ttl ( unlimited | <ttlval> );
         min-refresh-time <integer>;
         min-retry-time <integer>;
         multi-master <boolean>;
-        notify <notifytype>;
+        notify ( explicit | master-only | <boolean> );
         notify-delay <integer>;
         notify-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [
             dscp <integer> ];
@@ -786,6 +788,6 @@ zone <string> <optional_class> {
             | zonesub | external ) [ <string> ] <rrtypelist>; ... };
         use-alt-transfer-source <boolean>;
         zero-no-soa-ttl <boolean>;
-        zone-statistics <zonestat>;
+        zone-statistics ( full | terse | none | <boolean> );
 };
 
diff --git a/lib/isccfg/namedconf.c b/lib/isccfg/namedconf.c
index 613961c24f4..329665f7f9c 100644
--- a/lib/isccfg/namedconf.c
+++ b/lib/isccfg/namedconf.c
@@ -56,7 +56,8 @@ parse_enum_or_other(cfg_parser_t *pctx, const cfg_type_t *enumtype,
 		    const cfg_type_t *othertype, cfg_obj_t **ret);
 
 static void
-doc_enum_or_other(cfg_printer_t *pctx, const cfg_type_t *type);
+doc_enum_or_other(cfg_printer_t *pctx, const cfg_type_t *enumtype,
+		  const cfg_type_t *othertype);
 
 static isc_result_t
 parse_keyvalue(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
@@ -586,8 +587,12 @@ static isc_result_t
 parse_zonestat(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret) {
 	return (parse_enum_or_other(pctx, type, &cfg_type_boolean, ret));
 }
+static void
+doc_zonestat(cfg_printer_t *pctx, const cfg_type_t *type) {
+	doc_enum_or_other(pctx, type, &cfg_type_boolean);
+}
 static cfg_type_t cfg_type_zonestat = {
-	"zonestat", parse_zonestat, cfg_print_ustring, doc_enum_or_other,
+	"zonestat", parse_zonestat, cfg_print_ustring, doc_zonestat,
 	&cfg_rep_string, zonestat_enums
 };
 
@@ -927,8 +932,7 @@ parse_optional_response(cfg_parser_t *pctx, const cfg_type_t *type,
 
 static void
 doc_optional_response(cfg_printer_t *pctx, const cfg_type_t *type) {
-	UNUSED(type);
-	cfg_print_cstr(pctx, "[ ( drop | fail ) ]");
+	doc_enum_or_other(pctx, type, &cfg_type_void);
 }
 
 static cfg_type_t cfg_type_responsetype = {
@@ -2073,9 +2077,14 @@ parse_size(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret) {
 	return (parse_enum_or_other(pctx, type, &cfg_type_sizeval, ret));
 }
 
+static void
+doc_size(cfg_printer_t *pctx, const cfg_type_t *type) {
+	doc_enum_or_other(pctx, type, &cfg_type_sizeval);
+}
+
 static const char *size_enums[] = { "unlimited", "default", NULL };
 static cfg_type_t cfg_type_size = {
-	"size", parse_size, cfg_print_ustring, cfg_doc_terminal,
+	"size", parse_size, cfg_print_ustring, doc_size,
 	&cfg_rep_string, size_enums
 };
 
@@ -2137,12 +2146,34 @@ parse_enum_or_other(cfg_parser_t *pctx, const cfg_type_t *enumtype,
 }
 
 static void
-doc_enum_or_other(cfg_printer_t *pctx, const cfg_type_t *type) {
-	cfg_doc_terminal(pctx, type);
-#if 0 /* XXX */
-	cfg_print_chars(pctx, "( ", 2);...
-#endif
+doc_enum_or_other(cfg_printer_t *pctx, const cfg_type_t *enumtype,
+		  const cfg_type_t *othertype)
+{
+	const char * const *p;
+	isc_boolean_t first = ISC_TRUE;
 
+	/*
+	 * If othertype is cfg_type_void, it means that enumtype is
+	 * optional.
+	 */
+
+	if (othertype == &cfg_type_void)
+		cfg_print_cstr(pctx, "[ ");
+	cfg_print_cstr(pctx, "( ");
+	for (p = enumtype->of; *p != NULL; p++) {
+		if (!first)
+			cfg_print_cstr(pctx, " | ");
+		first = ISC_FALSE;
+		cfg_print_cstr(pctx, *p);
+	}
+	if (othertype != &cfg_type_void) {
+		if (!first)
+			cfg_print_cstr(pctx, " | ");
+		cfg_doc_terminal(pctx, othertype);
+	}
+	cfg_print_cstr(pctx, " )");
+	if (othertype == &cfg_type_void)
+		cfg_print_cstr(pctx, " ]");
 }
 
 static isc_result_t
@@ -2189,8 +2220,12 @@ static isc_result_t
 parse_dialup_type(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret) {
 	return (parse_enum_or_other(pctx, type, &cfg_type_boolean, ret));
 }
+static void
+doc_dialup_type(cfg_printer_t *pctx, const cfg_type_t *type) {
+	doc_enum_or_other(pctx, type, &cfg_type_boolean);
+}
 static cfg_type_t cfg_type_dialuptype = {
-	"dialuptype", parse_dialup_type, cfg_print_ustring, doc_enum_or_other,
+	"dialuptype", parse_dialup_type, cfg_print_ustring, doc_dialup_type,
 	&cfg_rep_string, dialup_enums
 };
 
@@ -2199,18 +2234,28 @@ static isc_result_t
 parse_notify_type(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret) {
 	return (parse_enum_or_other(pctx, type, &cfg_type_boolean, ret));
 }
+static void
+doc_notify_type(cfg_printer_t *pctx, const cfg_type_t *type) {
+	doc_enum_or_other(pctx, type, &cfg_type_boolean);
+}
 static cfg_type_t cfg_type_notifytype = {
-	"notifytype", parse_notify_type, cfg_print_ustring, doc_enum_or_other,
+	"notifytype", parse_notify_type, cfg_print_ustring, doc_notify_type,
 	&cfg_rep_string, notify_enums,
 };
 
 static const char *ixfrdiff_enums[] = { "master", "slave", NULL };
 static isc_result_t
-parse_ixfrdiff_type(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret) {
+parse_ixfrdiff_type(cfg_parser_t *pctx, const cfg_type_t *type,
+		    cfg_obj_t **ret)
+{
 	return (parse_enum_or_other(pctx, type, &cfg_type_boolean, ret));
 }
+static void
+doc_ixfrdiff_type(cfg_printer_t *pctx, const cfg_type_t *type) {
+	doc_enum_or_other(pctx, type, &cfg_type_boolean);
+}
 static cfg_type_t cfg_type_ixfrdifftype = {
-	"ixfrdiff", parse_ixfrdiff_type, cfg_print_ustring, doc_enum_or_other,
+	"ixfrdiff", parse_ixfrdiff_type, cfg_print_ustring, doc_ixfrdiff_type,
 	&cfg_rep_string, ixfrdiff_enums,
 };
 
@@ -2220,9 +2265,13 @@ parse_filter_aaaa(cfg_parser_t *pctx, const cfg_type_t *type,
 		     cfg_obj_t **ret) {
 	return (parse_enum_or_other(pctx, type, &cfg_type_boolean, ret));
 }
+static void
+doc_filter_aaaa(cfg_printer_t *pctx, const cfg_type_t *type) {
+	doc_enum_or_other(pctx, type, &cfg_type_boolean);
+}
 static cfg_type_t cfg_type_filter_aaaa = {
 	"filter_aaaa", parse_filter_aaaa, cfg_print_ustring,
-	doc_enum_or_other, &cfg_rep_string, filter_aaaa_enums,
+	doc_filter_aaaa, &cfg_rep_string, filter_aaaa_enums,
 };
 
 static keyword_type_t key_kw = { "key", &cfg_type_astring };
@@ -2845,8 +2894,13 @@ parse_logversions(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret) {
 	return (parse_enum_or_other(pctx, type, &cfg_type_uint32, ret));
 }
 
+static void
+doc_logversions(cfg_printer_t *pctx, const cfg_type_t *type) {
+	doc_enum_or_other(pctx, type, &cfg_type_uint32);
+}
+
 static cfg_type_t cfg_type_logversions = {
-	"logversions", parse_logversions, cfg_print_ustring, cfg_doc_terminal,
+	"logversions", parse_logversions, cfg_print_ustring, doc_logversions,
 	&cfg_rep_string, logversions_enums
 };
 
@@ -3270,11 +3324,16 @@ parse_maxttl(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret) {
 	return (parse_enum_or_other(pctx, type, &cfg_type_ttlval, ret));
 }
 
+static void
+doc_maxttl(cfg_printer_t *pctx, const cfg_type_t *type) {
+	doc_enum_or_other(pctx, type, &cfg_type_ttlval);
+}
+
 /*%
  * A size or "unlimited", but not "default".
  */
 static const char *maxttl_enums[] = { "unlimited", NULL };
 static cfg_type_t cfg_type_maxttl = {
-	"maxttl_no_default", parse_maxttl, cfg_print_ustring, cfg_doc_terminal,
+	"maxttl_no_default", parse_maxttl, cfg_print_ustring, doc_maxttl,
 	&cfg_rep_string, maxttl_enums
 };