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

1 files changed, 7 insertions, 4 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