Update config framework/sorcery with types/options without documentation

There are times when a configuration option should not have documentation.

1. Some options are registered with a particular object merely as a warning to
   users. These options aren't even really 'deprecated' - which has its own
   separate API call - they are actually provided by a different configuration
   file. The options are merely registered so that the user gets a warning that
   a different configuration file provides the item.

2. Some object types - most notably some used by modules that use sorcery - are
   completely internal and should never be shown to the user.

3. Sorcery itself has several 'hidden' fields that should never be shown to a
   user.

This patch updates the configuration framework and sorcery with additional API
calls that allow a module to register types as internal and options as not
requiring documentation. This bypasses the XML documentation checking.

This patch also re-enables the strict XML documentation checking in trunk, as
well as updates some documentation that was missing.

Review: https://reviewboard.asterisk.org/r/2785/

(closes issue ASTERISK-22359)
Reported by: Matt Jordan

(closes issue ASTERISK-22112)
Reported by: Rusty Newton



git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@397524 65c4cc65-6c06-0410-ace0-fbb531ad65f3

3 files changed, 32 insertions, 28 deletions

diff --git a/main/config_options.c b/main/config_options.c
index 2770558df..20e993507 100644
--- a/main/config_options.c
+++ b/main/config_options.c
@@ -69,6 +69,7 @@ struct aco_option {
 	enum aco_option_type type;
 	aco_option_handler handler;
 	unsigned int flags;
+	unsigned int no_doc:1;
 	unsigned char deprecated:1;
 	size_t argc;
 	intptr_t args[0];
@@ -183,7 +184,7 @@ static int link_option_to_types(struct aco_info *info, struct aco_type **types,
 		}
 		if (!ao2_link(type->internal->opts, opt)
 #ifdef AST_XML_DOCS
-				|| xmldoc_update_config_option(types, info->module, opt->name, type->name, opt->default_val, opt->match_type == ACO_REGEX, opt->type)
+				|| (!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 */
 		) {
 			do {
@@ -276,7 +277,8 @@ static struct ast_xml_doc_item *find_xmldoc_type(struct ast_xml_doc_item *config
 #endif /* AST_XML_DOCS */
 
 int __aco_option_register(struct aco_info *info, const char *name, enum aco_matchtype matchtype, struct aco_type **types,
-	const char *default_val, enum aco_option_type kind, aco_option_handler handler, unsigned int flags, size_t argc, ...)
+	const char *default_val, enum aco_option_type kind, aco_option_handler handler, unsigned int flags,
+	unsigned int no_doc, size_t argc, ...)
 {
 	struct aco_option *opt;
 	va_list ap;
@@ -313,6 +315,7 @@ int __aco_option_register(struct aco_info *info, const char *name, enum aco_matc
 	opt->handler = handler;
 	opt->flags = flags;
 	opt->argc = argc;
+	opt->no_doc = no_doc;
 
 	if (!opt->handler && !(opt->handler = ast_config_option_default_handler(opt->type))) {
 		/* This should never happen */
@@ -765,7 +768,7 @@ int aco_info_init(struct aco_info *info)
 				goto error;
 			}
 #ifdef AST_XML_DOCS
-			if (xmldoc_update_config_type(info->module, type->name, type->category, type->matchfield, type->matchvalue, type->category_match == ACO_WHITELIST)) {
+			if (!type->hidden && xmldoc_update_config_type(info->module, type->name, type->category, type->matchfield, type->matchvalue, type->category_match == ACO_WHITELIST)) {
 				goto error;
 			}
 #endif /* AST_XML_DOCS */
@@ -917,7 +920,7 @@ static char *complete_config_option(const char *module, const char *option, cons
 /* Define as 0 if we want to allow configurations to be registered without
  * documentation
  */
-#define XMLDOC_STRICT 0
+#define XMLDOC_STRICT 1
 
 /*! \internal
  * \brief Update the XML documentation for a config type based on its registration
diff --git a/main/features_config.c b/main/features_config.c
index bebd593d1..ac4a1fec0 100644
--- a/main/features_config.c
+++ b/main/features_config.c
@@ -1654,39 +1654,39 @@ static int load_config(void)
 	aco_option_register_custom(&cfg_info, "pickupfailsound", ACO_EXACT, global_options,
 			DEFAULT_PICKUPFAILSOUND, pickup_handler, 0);
 
-	aco_option_register_custom(&cfg_info, "context", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "context", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "parkext", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "parkext", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "parkext_exclusive", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "parkext_exclusive", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "parkinghints", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "parkinghints", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "parkedmusicclass", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "parkedmusicclass", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "parkingtime", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "parkingtime", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "parkpos", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "parkpos", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "findslot", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "findslot", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "parkedcalltransfers", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "parkedcalltransfers", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "parkedcallreparking", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "parkedcallreparking", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "parkedcallhangup", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "parkedcallhangup", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "parkedcallrecording", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "parkedcallrecording", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "comebackcontext", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "comebackcontext", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "comebacktoorigin", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "comebacktoorigin", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "comebackdialtime", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "comebackdialtime", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "parkeddynamic", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "parkeddynamic", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
-	aco_option_register_custom(&cfg_info, "adsipark", ACO_EXACT, global_options,
+	aco_option_register_custom_nodoc(&cfg_info, "adsipark", ACO_EXACT, global_options,
 			"", unsupported_handler, 0);
 
 	aco_option_register_custom(&cfg_info, "blindxfer", ACO_EXACT, featuremap_options,
diff --git a/main/sorcery.c b/main/sorcery.c
index bb803c116..b2bb87915 100644
--- a/main/sorcery.c
+++ b/main/sorcery.c
@@ -575,7 +575,7 @@ static int sorcery_extended_fields_handler(const void *obj, struct ast_variable
 	return 0;
 }
 
-int ast_sorcery_object_register(struct ast_sorcery *sorcery, const char *type, aco_type_item_alloc alloc, sorcery_transform_handler transform, sorcery_apply_handler apply)
+int __ast_sorcery_object_register(struct ast_sorcery *sorcery, const char *type, unsigned int hidden, aco_type_item_alloc alloc, sorcery_transform_handler transform, sorcery_apply_handler apply)
 {
 	RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
 
@@ -587,6 +587,7 @@ int ast_sorcery_object_register(struct ast_sorcery *sorcery, const char *type, a
 	object_type->type.type = ACO_ITEM;
 	object_type->type.category = ".?";
 	object_type->type.item_alloc = alloc;
+	object_type->type.hidden = hidden;
 
 	object_type->transform = transform;
 	object_type->apply = apply;
@@ -639,13 +640,13 @@ int ast_sorcery_object_fields_register(struct ast_sorcery *sorcery, const char *
 	object_field->multiple_handler = sorcery_handler;
 
 	ao2_link(object_type->fields, object_field);
-	__aco_option_register(object_type->info, regex, ACO_REGEX, object_type->file->types, "", OPT_CUSTOM_T, config_handler, 0, 0);
+	__aco_option_register(object_type->info, regex, ACO_REGEX, object_type->file->types, "", OPT_CUSTOM_T, config_handler, 0, 1, 0);
 
 	return 0;
 }
 
 int __ast_sorcery_object_field_register(struct ast_sorcery *sorcery, const char *type, const char *name, const char *default_val, enum aco_option_type opt_type,
-					aco_option_handler config_handler, sorcery_field_handler sorcery_handler, unsigned int flags, size_t argc, ...)
+					aco_option_handler config_handler, sorcery_field_handler sorcery_handler, unsigned int flags, unsigned int no_doc, size_t argc, ...)
 {
 	RAII_VAR(struct ast_sorcery_object_type *, object_type, ao2_find(sorcery->types, type, OBJ_KEY), ao2_cleanup);
 	RAII_VAR(struct ast_sorcery_object_field *, object_field, NULL, ao2_cleanup);
@@ -677,15 +678,15 @@ int __ast_sorcery_object_field_register(struct ast_sorcery *sorcery, const char
 
 	/* TODO: Improve this hack */
 	if (!argc) {
-		__aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, argc);
+		__aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, no_doc, argc);
 	} else if (argc == 1) {
-		__aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, argc,
+		__aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, no_doc, argc,
 				      object_field->args[0]);
 	} else if (argc == 2) {
-		__aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, argc,
+		__aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, no_doc, argc,
 				      object_field->args[0], object_field->args[1]);
 	} else if (argc == 3) {
-		__aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, argc,
+		__aco_option_register(object_type->info, name, ACO_EXACT, object_type->file->types, default_val, opt_type, config_handler, flags, no_doc, argc,
 				      object_field->args[0], object_field->args[1], object_field->args[2]);
 	} else {
 		ast_assert(0); /* The hack... she does us no good for this */