[asterisk-commits] twilson: branch twilson/config_docs r370588 - in /team/twilson/config_docs: i...

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Mon Jul 30 14:46:02 CDT 2012


Author: twilson
Date: Mon Jul 30 14:45:54 2012
New Revision: 370588

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=370588
Log:
Address mjordan's review

Modified:
    team/twilson/config_docs/include/asterisk/xml.h
    team/twilson/config_docs/include/asterisk/xmldoc.h
    team/twilson/config_docs/main/config_options.c
    team/twilson/config_docs/main/xml.c
    team/twilson/config_docs/main/xmldoc.c

Modified: team/twilson/config_docs/include/asterisk/xml.h
URL: http://svnview.digium.com/svn/asterisk/team/twilson/config_docs/include/asterisk/xml.h?view=diff&rev=370588&r1=370587&r2=370588
==============================================================================
--- team/twilson/config_docs/include/asterisk/xml.h (original)
+++ team/twilson/config_docs/include/asterisk/xml.h Mon Jul 30 14:45:54 2012
@@ -215,7 +215,7 @@
 int ast_xml_xpath_num_results(struct ast_xml_xpath_results *results);
 
 /*! \brief Return the first result node of an XPath query */
-struct ast_xml_node *ast_xml_xpath_results(struct ast_xml_xpath_results *results);
+struct ast_xml_node *ast_xml_xpath_get_first_result(struct ast_xml_xpath_results *results);
 
 /*! \brief Execute an XPath query on an XML document */
 struct ast_xml_xpath_results *ast_xml_query(struct ast_xml_doc *doc, const char *xpath_str);

Modified: team/twilson/config_docs/include/asterisk/xmldoc.h
URL: http://svnview.digium.com/svn/asterisk/team/twilson/config_docs/include/asterisk/xmldoc.h?view=diff&rev=370588&r1=370587&r2=370588
==============================================================================
--- team/twilson/config_docs/include/asterisk/xmldoc.h (original)
+++ team/twilson/config_docs/include/asterisk/xmldoc.h Mon Jul 30 14:45:54 2012
@@ -77,8 +77,11 @@
  * \param object_name The config type name
  * \param default_value The option's default value
  * \param regex Whether or not the value is matched via regex (non-zero = yes)
+ *
+ * \retval non-zero failure
+ * \retval 0 success
  */
-void ast_xmldoc_update_config_option(const char *module, const char *name, const char *object_name, const char *default_value, unsigned int regex);
+int ast_xmldoc_update_config_option(const char *module, const char *name, const char *object_name, const char *default_value, unsigned int regex);
 
 /*! \brief Update the XML for an ACO type
  * \param module The module name
@@ -87,8 +90,11 @@
  * \param matchfield The field that needs to be matched, if applicable
  * \param matchvalue The value of the matchfield needed for a match, if applicable
  * \param matches Whether the category regex specifies a whitelist or blacklist (non-zero = whitelist)
+ *
+ * \retval non-zero failure
+ * \retval 0 success
  */
-void ast_xmldoc_update_config_type(const char *module, const char *name, const char *category, const char *matchfield, const char *matchvalue, unsigned int matches);
+int ast_xmldoc_update_config_type(const char *module, const char *name, const char *category, const char *matchfield, const char *matchvalue, unsigned int matches);
 
 /*!
  *  \brief Get the syntax for a specified application or function.

Modified: team/twilson/config_docs/main/config_options.c
URL: http://svnview.digium.com/svn/asterisk/team/twilson/config_docs/main/config_options.c?view=diff&rev=370588&r1=370587&r2=370588
==============================================================================
--- team/twilson/config_docs/main/config_options.c (original)
+++ team/twilson/config_docs/main/config_options.c Mon Jul 30 14:45:54 2012
@@ -73,7 +73,9 @@
 	intptr_t args[0];
 };
 
+#ifdef AST_XML_DOCS
 static struct ao2_container *xmldocs;
+#endif /* AST_XML_DOCS */
 
 void *aco_pending_config(struct aco_info *info)
 {
@@ -153,15 +155,16 @@
 	struct aco_type *type;
 
 	while ((type = types[idx++])) {
-		if (!ao2_link(type->internal->opts, opt)) {
+		if (!ao2_link(type->internal->opts, opt)
+#ifdef AST_XML_DOCS
+				|| ast_xmldoc_update_config_option(info->module, opt->name, type->name, opt->default_val, opt->match_type == ACO_REGEX)
+#endif /* AST_XML_DOCS */
+		) {
 			while (--idx) {
 				ao2_unlink(types[idx]->internal->opts, opt);
 			}
 			return -1;
 		}
-#ifdef AST_XML_DOCS
-		ast_xmldoc_update_config_option(info->module, opt->name, type->name, opt->default_val, opt->match_type == ACO_REGEX);
-#endif
 	}
 	return 0;
 }
@@ -232,7 +235,7 @@
 	}
 	return iter;
 }
-#endif
+#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, ...)
@@ -294,13 +297,13 @@
 		if (!config_info || !(config_option = find_xmldoc_option(config_info, types, name))) {
 			ast_log(LOG_ERROR, "XML Documentation for option '%s' in modules '%s' not found!\n", name, info->module);
 			/* ao2_ref(opt, -1);
-			 * return -1; */
+			 * * return -1; */
 			return 0;
 		}
 		config_option->regex = opt->match_type == ACO_REGEX;
 		ast_string_field_set(config_option, default_value, opt->default_val);
 	}
-#endif
+#endif /* AST_XML_DOCS */
 
 	return 0;
 }
@@ -581,10 +584,10 @@
 	}
 
 	if (res != ACO_PROCESS_OK) {
-	   goto end;
-	}
-
-	if (info->pre_apply_config && (info->pre_apply_config()))  {
+		goto end;
+	}
+
+	if (info->pre_apply_config && (info->pre_apply_config())) {
 		res = ACO_PROCESS_ERROR;
 		goto end;
 	}
@@ -685,6 +688,7 @@
 	return 0;
 }
 
+#ifdef AST_XML_DOCS
 static void update_runtime_type_docs(const char *module, struct aco_type *type)
 {
 	RAII_VAR(struct ast_xml_doc_item *, config_info, ao2_find(xmldocs, module, OBJ_KEY), ao2_cleanup);
@@ -702,6 +706,7 @@
 		ast_str_append(&config_type->syntax, 0, "matchfield: %s = %s\n", type->matchfield, type->matchvalue);
 	}
 }
+#endif /* AST_XML_DOCS */
 
 int aco_info_init(struct aco_info *info)
 {
@@ -719,9 +724,11 @@
 				goto error;
 			}
 #ifdef AST_XML_DOCS
-			ast_xmldoc_update_config_type(info->module, type->name, type->category, type->matchfield, type->matchvalue, type->category_match == ACO_WHITELIST);
+			if (ast_xmldoc_update_config_type(info->module, type->name, type->category, type->matchfield, type->matchvalue, type->category_match == ACO_WHITELIST)) {
+				goto error;
+			}
 			update_runtime_type_docs(info->module, type);
-#endif
+#endif /* AST_XML_DOCS */
 		}
 	}
 
@@ -777,6 +784,7 @@
 	return 0;
 }
 
+#ifdef AST_XML_DOCS
 static char *complete_config_module(const char *word, int pos, int state)
 {
 	char *c = NULL;
@@ -879,7 +887,7 @@
 	tmp = item;
 	while ((tmp = tmp->next)) {
 		if (!strcasecmp(tmp->type, "configObject")) {
-		   	ast_cli(a->fd, "%s\n", tmp->name);
+			ast_cli(a->fd, "%s\n", tmp->name);
 		}
 	}
 	return CLI_SUCCESS;
@@ -915,7 +923,7 @@
 	tmp = item;
 	while ((tmp = tmp->next)) {
 		if (!strcasecmp(tmp->type, "configObject") && !strcasecmp(tmp->name, a->argv[4])) {
-		   	ast_cli(a->fd, "%s\n", tmp->name);
+			ast_cli(a->fd, "%s\n", tmp->name);
 			ast_cli(a->fd, "Synopsis: %s\n", AS_OR(tmp->synopsis, "n/a"));
 			ast_cli(a->fd, "Description:\n\t%s\n", AS_OR(tmp->description, "n/a"));
 			ast_cli(a->fd, "Syntax:\n\t%s\n", AS_OR(tmp->syntax, "n/a"));
@@ -993,7 +1001,7 @@
 	tmp = item;
 	while ((tmp = tmp->next)) {
 		if (!strcasecmp(tmp->type, "configOption") && !strcasecmp(tmp->ref, a->argv[4]) && !strcasecmp(tmp->name, a->argv[5])) {
-		   	ast_cli(a->fd, "<%s> %s\n", tmp->ref, tmp->name);
+			ast_cli(a->fd, "<%s> %s\n", tmp->ref, tmp->name);
 			ast_cli(a->fd, "Default: %s\n", S_OR(tmp->default_value, "n/a"));
 			ast_cli(a->fd, "Synopsis: %s\n", AS_OR(tmp->synopsis, "n/a"));
 			ast_cli(a->fd, "Description:\n\t%s\n", AS_OR(tmp->description, "n/a"));
@@ -1012,23 +1020,21 @@
 
 static void aco_deinit(void)
 {
-#ifdef AST_XML_DOCS
 	ast_cli_unregister(cli_aco);
 	ao2_cleanup(xmldocs);
-#endif
-}
+}
+#endif /* AST_XML_DOCS */
 
 int aco_init(void)
 {
-
+#ifdef AST_XML_DOCS
 	ast_register_atexit(aco_deinit);
-#ifdef AST_XML_DOCS
 	if (!(xmldocs = ast_xmldoc_build_documentation("configInfo"))) {
 		ast_log(LOG_ERROR, "Couldn't build config documentation\n");
 		return -1;
 	}
 	ast_cli_register_multiple(cli_aco, ARRAY_LEN(cli_aco));
-#endif
+#endif /* AST_XML_DOCS */
 	return 0;
 }
 
@@ -1048,7 +1054,7 @@
 			ast_parse_arg(var->value, flags, field, (int) opt->args[1], (int) opt->args[2]);
 		if (res) {
 			if (opt->flags & PARSE_RANGE_DEFAULTS) {
-				ast_log(LOG_WARNING, "Failed to set %s=%s. Set to  %d instead due to range limit (%d, %d)\n", var->name, var->value, *field, (int) opt->args[1], (int) opt->args[2]);
+				ast_log(LOG_WARNING, "Failed to set %s=%s. Set to %d instead due to range limit (%d, %d)\n", var->name, var->value, *field, (int) opt->args[1], (int) opt->args[2]);
 				res = 0;
 			} else if (opt->flags & PARSE_DEFAULT) {
 				ast_log(LOG_WARNING, "Failed to set %s=%s, Set to default value %d instead.\n", var->name, var->value, *field);
@@ -1078,7 +1084,7 @@
 			ast_parse_arg(var->value, flags, field, (unsigned int) opt->args[1], (unsigned int) opt->args[2]);
 		if (res) {
 			if (opt->flags & PARSE_RANGE_DEFAULTS) {
-				ast_log(LOG_WARNING, "Failed to set %s=%s. Set to  %d instead due to range limit (%d, %d)\n", var->name, var->value, *field, (int) opt->args[1], (int) opt->args[2]);
+				ast_log(LOG_WARNING, "Failed to set %s=%s. Set to %d instead due to range limit (%d, %d)\n", var->name, var->value, *field, (int) opt->args[1], (int) opt->args[2]);
 				res = 0;
 			} else if (opt->flags & PARSE_DEFAULT) {
 				ast_log(LOG_WARNING, "Failed to set %s=%s, Set to default value %d instead.\n", var->name, var->value, *field);

Modified: team/twilson/config_docs/main/xml.c
URL: http://svnview.digium.com/svn/asterisk/team/twilson/config_docs/main/xml.c?view=diff&rev=370588&r1=370587&r2=370588
==============================================================================
--- team/twilson/config_docs/main/xml.c (original)
+++ team/twilson/config_docs/main/xml.c Mon Jul 30 14:45:54 2012
@@ -318,7 +318,7 @@
 	return (struct ast_xml_node *) ((xmlNode *) node)->parent;
 }
 
-struct ast_xml_node *ast_xml_xpath_results(struct ast_xml_xpath_results *results)
+struct ast_xml_node *ast_xml_xpath_get_first_result(struct ast_xml_xpath_results *results)
 {
 	return (struct ast_xml_node *) ((xmlXPathObjectPtr) results)->nodesetval->nodeTab[0];
 }

Modified: team/twilson/config_docs/main/xmldoc.c
URL: http://svnview.digium.com/svn/asterisk/team/twilson/config_docs/main/xmldoc.c?view=diff&rev=370588&r1=370587&r2=370588
==============================================================================
--- team/twilson/config_docs/main/xmldoc.c (original)
+++ team/twilson/config_docs/main/xmldoc.c Mon Jul 30 14:45:54 2012
@@ -2297,68 +2297,81 @@
 	return results;
 }
 
-void ast_xmldoc_update_config_type(const char *module, const char *name, const char *category, const char *matchfield, const char *matchvalue, unsigned int matches)
+int ast_xmldoc_update_config_type(const char *module, const char *name, const char *category, const char *matchfield, const char *matchvalue, unsigned int matches)
 {
 	RAII_VAR(struct ast_xml_xpath_results *, results, NULL, ast_xml_xpath_results_free);
 	struct ast_xml_node *type, *syntax, *matchinfo, *tmp;
 
-	/* If we already have a syntax element, bail */
-	if ((results = query_xmldocs("//configInfo[@name='%s']/*/configObject[@name='%s']/syntax", module, name))) {
-		return;
-	}
-
-	if (!(results = query_xmldocs("//configInfo[@name='%s']/*/configObject[@name='%s']", module, name))) {
-		return;
-	}
-
-	if (!(type = ast_xml_xpath_results(results))) {
-		return;
+	/* If we already have a syntax element, bail. This isn't an error, since we may unload a module which 
+	 * has updated the docs and then load it again. */
+	if ((results = query_xmldocs("//configInfo[@name='%s']/*/configObject[@name='%s']/syntax", name, module))) {
+		return 0;
+	}
+
+	if (!(results = query_xmldocs("//configInfo[@name='%s']/*/configObject[@name='%s']", name, module))) {
+		ast_log(LOG_WARNING, "Cannot update type '%s' in module '%s' because it has no existing documentation!\n", name, module);
+		return -1;
+	}
+
+	if (!(type = ast_xml_xpath_get_first_result(results))) {
+		ast_log(LOG_WARNING, "Could not retrieve documentation for type '%s' in module '%s'\n", name, module);
+		return -1;
 	}
 
 	if (!(syntax = ast_xml_new_child(type, "syntax"))) {
-		return;
+		ast_log(LOG_WARNING, "Could not create syntax node for type '%s' in module '%s'\n", name, module);
+		return -1;
 	}
 
 	if (!(matchinfo = ast_xml_new_child(syntax, "matchInfo"))) {
-		return;
+		ast_log(LOG_WARNING, "Could not create matchInfo node for type '%s' in module '%s'\n", name, module);
+		return -1;
 	}
 
 	if (!(tmp = ast_xml_new_child(matchinfo, "category"))) {
-		return;
+		ast_log(LOG_WARNING, "Could not create category node for type '%s' in module '%s'\n", name, module);
+		return -1;
 	}
 
 	ast_xml_set_text(tmp, category);
 	ast_xml_set_attribute(tmp, "match", matches ? "true" : "false");
 
 	if (!ast_strlen_zero(matchfield) && !(tmp = ast_xml_new_child(matchinfo, "field"))) {
-		return;
+		ast_log(LOG_WARNING, "Could not add %s attribute for type '%s' in module '%s'\n", matchfield, name, module);
+		return -1;
 	}
 
 	ast_xml_set_attribute(tmp, "name", matchfield);
 	ast_xml_set_text(tmp, matchvalue);
-}
-
-void ast_xmldoc_update_config_option(const char *module, const char *name, const char *object_name, const char *default_value, unsigned int regex)
+
+	return 0;
+}
+
+int ast_xmldoc_update_config_option(const char *module, const char *name, const char *object_name, const char *default_value, unsigned int regex)
 {
 	RAII_VAR(struct ast_xml_xpath_results *, results, NULL, ast_xml_xpath_results_free);
 	struct ast_xml_node *option;
 
 	if (!(results = query_xmldocs("//configInfo[@name='%s']/*/configObject[@name='%s']/configOption[@name='%s']", module, object_name, name))) {
-		return;
-	}
-
-	if (!(option = ast_xml_xpath_results(results))) {
-		return;
+		ast_log(LOG_WARNING, "Could not find option '%s' with type '%s' in module '%s'\n", name, object_name, module);
+		return -1;
+	}
+
+	if (!(option = ast_xml_xpath_get_first_result(results))) {
+		ast_log(LOG_WARNING, "Could objtain results for option '%s' with type '%s' in module '%s'\n", name, object_name, module);
+		return -1;
 	}
 	ast_xml_set_attribute(option, "regex", regex ? "true" : "false");
 	ast_xml_set_attribute(option, "default", default_value);
+
+	return 0;
 }
 
 static void build_config_docs(struct ast_xml_node *cur, struct ast_xml_doc_item **tail)
 {
 	struct ast_xml_node *iter;
 	struct ast_xml_doc_item *item;
-	
+
 	for (iter = ast_xml_node_get_children(cur); iter; iter = ast_xml_node_get_next(iter)) {
 		if (strncasecmp(ast_xml_node_get_name(iter), "config", 6)) {
 			continue;
@@ -2530,7 +2543,7 @@
 	return CLI_SUCCESS;
 }
 
-static struct ast_cli_entry cli_dump_xmldocs = AST_CLI_DEFINE(handle_dump_docs, "Dump the XML docs to the screen");
+static struct ast_cli_entry cli_dump_xmldocs = AST_CLI_DEFINE(handle_dump_docs, "Dump the XML docs to the specified file");
 
 /*! \brief Close and unload XML documentation. */
 static void xmldoc_unload_documentation(void)




More information about the asterisk-commits mailing list