[Asterisk-code-review] config: Allow options to register when documentation is unav... (asterisk[master])

[Joshua Colp]

Joshua Colp has uploaded a new change for review.

  https://gerrit.asterisk.org/2078

Change subject: config: Allow options to register when documentation is unavailable.
......................................................................

config: Allow options to register when documentation is unavailable.

The config options framework is strict in that configuration options must
be documented unless XML documentation support is not available. In
practice this is useful as it ensures documentation exists however in
off-nominal cases this can cause strange problems.

If it is expected that a config option has a non-zero or non-empty
default value but the config option documentation is unavailable
this reasonable expectation will not be met. This can cause obscure
crashes and weirdness depending on how the code handles it.

This change tweaks the behavior to ensure that the config option
is still allowed to register and apply default values BUT can
not be explicitly set. If it is set then an error message is output
stating that documentation is unavailable and the option
can not be set.

This also does not remove the initial documentation error message that
is output on load when registering the configuration option.

ASTERISK-25725 #close

Change-Id: Iec42fca6b35f31326c33fcdc25473f6fd7bc8af8
---
M main/config_options.c
1 file changed, 14 insertions(+), 7 deletions(-)


  git pull ssh://gerrit.asterisk.org:29418/asterisk refs/changes/78/2078/1

diff --git a/main/config_options.c b/main/config_options.c
index 4ab7a5b..6c05696 100644
--- a/main/config_options.c
+++ b/main/config_options.c
@@ -71,6 +71,7 @@
 	aco_option_handler handler;
 	unsigned int flags;
 	unsigned int no_doc:1;
+	unsigned int doc_unavailable:1;
 	unsigned char deprecated:1;
 	size_t argc;
 	intptr_t args[0];
@@ -183,17 +184,17 @@
 			ast_log(LOG_ERROR, "Attempting to register option using uninitialized type\n");
 			return -1;
 		}
-		if (!ao2_link(type->internal->opts, opt)
-#ifdef AST_XML_DOCS
-				|| (!info->hidden &&
-					!opt->no_doc &&
-					xmldoc_update_config_option(types, info->module, opt->name, type->name, opt->default_val, opt->match_type == ACO_REGEX, opt->type))
-#endif /* AST_XML_DOCS */
-		) {
+		if (!ao2_link(type->internal->opts, opt)) {
 			do {
 				ao2_unlink(types[idx - 1]->internal->opts, opt);
 			} while (--idx);
 			return -1;
+		}
+#ifdef AST_XML_DOCS
+		if (!info->hidden && !opt->no_doc &&
+			xmldoc_update_config_option(types, info->module, opt->name, type->name, opt->default_val, opt->match_type == ACO_REGEX, opt->type)) {
+			opt->doc_unavailable = 1;
+#endif
 		}
 	}
 	/* The container(s) should hold the only ref to opt */
@@ -716,6 +717,12 @@
 		ast_log(LOG_ERROR, "BUG! Somehow a config option for %s/%s was created with no handler!\n", cat, var->name);
 		return -1;
 	}
+
+	if (opt->doc_unavailable) {
+		ast_log(LOG_ERROR, "Config option '%s' of type '%s' is not completely documented and can not be set\n", var->name, type->name);
+		return -1;
+	}
+
 	if (opt->handler(opt, var, obj)) {
 		ast_log(LOG_ERROR, "Error parsing %s=%s at line %d of %s\n", var->name, var->value, var->lineno, var->file);
 		return -1;

-- 
To view, visit https://gerrit.asterisk.org/2078
To unsubscribe, visit https://gerrit.asterisk.org/settings

Gerrit-MessageType: newchange
Gerrit-Change-Id: Iec42fca6b35f31326c33fcdc25473f6fd7bc8af8
Gerrit-PatchSet: 1
Gerrit-Project: asterisk
Gerrit-Branch: master
Gerrit-Owner: Joshua Colp <jcolp at digium.com>