[asterisk-commits] mjordan: branch mjordan/manager-events r368552 - in /team/mjordan/manager-eve...
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Tue Jun 5 11:32:26 CDT 2012
Author: mjordan
Date: Tue Jun 5 11:32:17 2012
New Revision: 368552
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=368552
Log:
Update manager event documentation with xmldoc changes
* Updated schema to just use synopsis instead of reason
* Updated xmldoc with parsing support for events
* Updated dtd with new schema
Modified:
team/mjordan/manager-events/Makefile
team/mjordan/manager-events/apps/app_dial.c
team/mjordan/manager-events/doc/appdocsxml.dtd
team/mjordan/manager-events/include/asterisk/xmldoc.h
team/mjordan/manager-events/main/xmldoc.c
Modified: team/mjordan/manager-events/Makefile
URL: http://svnview.digium.com/svn/asterisk/team/mjordan/manager-events/Makefile?view=diff&rev=368552&r1=368551&r2=368552
==============================================================================
--- team/mjordan/manager-events/Makefile (original)
+++ team/mjordan/manager-events/Makefile Tue Jun 5 11:32:17 2012
@@ -502,7 +502,7 @@
done
@echo
@echo "</docs>" >> $@
-# @$(PYTHON) build_tools/post_process_documentation.py -i $@ -o "doc/core-en_US.xml"
+ @$(PYTHON) build_tools/post_process_documentation.py -i $@ -o "doc/core-en_US.xml"
endif
validate-docs: doc/core-en_US.xml
Modified: team/mjordan/manager-events/apps/app_dial.c
URL: http://svnview.digium.com/svn/asterisk/team/mjordan/manager-events/apps/app_dial.c?view=diff&rev=368552&r1=368551&r2=368552
==============================================================================
--- team/mjordan/manager-events/apps/app_dial.c (original)
+++ team/mjordan/manager-events/apps/app_dial.c Tue Jun 5 11:32:17 2012
@@ -825,7 +825,7 @@
struct ast_channel *chans[] = { src, dst };
/*** DOCUMENTATION
<managerEventInstance>
- <reason>Called when a dial event is started.</reason>
+ <synopsis>Raised when a dial action has started.</synopsis>
<syntax>
<parameter name="SubEvent">
<para>The sub event</para>
@@ -857,7 +857,7 @@
{
/*** DOCUMENTATION
<managerEventInstance>
- <reason>Called when a dial event is ended.</reason>
+ <synopsis>Raised when a dial action has ended.</synopsis>
</managerEventInstance>
***/
ast_manager_event(src, EVENT_FLAG_CALL, "Dial",
Modified: team/mjordan/manager-events/doc/appdocsxml.dtd
URL: http://svnview.digium.com/svn/asterisk/team/mjordan/manager-events/doc/appdocsxml.dtd?view=diff&rev=368552&r1=368551&r2=368552
==============================================================================
--- team/mjordan/manager-events/doc/appdocsxml.dtd (original)
+++ team/mjordan/manager-events/doc/appdocsxml.dtd Tue Jun 5 11:32:17 2012
@@ -33,7 +33,7 @@
<!ATTLIST managerEvent name CDATA #REQUIRED>
<!ATTLIST managerEvent language CDATA #REQUIRED>
- <!ELEMENT managerEventInstance (reason,syntax?,see-also?,xi:include?)*>
+ <!ELEMENT managerEventInstance (synopsis?,syntax?,description?,see-also?)*>
<!ATTLIST managerEventInstance class CDATA #REQUIRED>
<!ELEMENT see-also (ref|xi:include)*>
@@ -45,8 +45,6 @@
<!ELEMENT syntax (parameter|xi:include)*>
<!ATTLIST syntax argsep CDATA ",">
-
- <!ELEMENT reason (#PCDATA)>
<!ELEMENT description (para|note|warning|variablelist|enumlist|xi:include)*>
Modified: team/mjordan/manager-events/include/asterisk/xmldoc.h
URL: http://svnview.digium.com/svn/asterisk/team/mjordan/manager-events/include/asterisk/xmldoc.h?view=diff&rev=368552&r1=368551&r2=368552
==============================================================================
--- team/mjordan/manager-events/include/asterisk/xmldoc.h (original)
+++ team/mjordan/manager-events/include/asterisk/xmldoc.h Tue Jun 5 11:32:17 2012
@@ -23,6 +23,7 @@
#include "asterisk/xml.h"
#include "asterisk/stringfields.h"
+#include "asterisk/strings.h"
/*! \brief From where the documentation come from, this structure is useful for
* use it inside application/functions/manager actions structure. */
@@ -31,10 +32,13 @@
AST_STATIC_DOC /*!< From application/function registration */
};
+#ifndef AST_XML_DOCS
+#define AST_XML_DOCS 1
+#endif
+
#ifdef AST_XML_DOCS
struct ao2_container;
-struct ast_str;
/*! \brief Struct that contains the XML documentation for a particular item. Note
* that this is an ao2 ref counted object.
@@ -43,23 +47,25 @@
* Each of the ast_str objects are built from the corresponding ast_xmldoc_build_*
* calls
*/
-struct ast_xml_doc {
+struct ast_xml_doc_item {
/*!< The syntax of the item */
struct ast_str *syntax;
/*!< Seealso tagged information, if it exists */
struct ast_str *seealso;
/*!< The arguments to the item */
- struct ast_str *arguments:
+ struct ast_str *arguments;
/*!< A synopsis of the item */
struct ast_str *synopsis;
/*!< A description of the item */
struct ast_str *description;
AST_DECLARE_STRING_FIELDS(
- /*!< The name of the item. Must be unique across all items of a particular type */
+ /*!< The name of the item */
AST_STRING_FIELD(name);
/*!< The type of the item */
AST_STRING_FIELD(type);
);
+ /*!< The next XML documentation item that matches the same name/item type */
+ struct ast_xml_doc_item *next;
};
/*!
Modified: team/mjordan/manager-events/main/xmldoc.c
URL: http://svnview.digium.com/svn/asterisk/team/mjordan/manager-events/main/xmldoc.c?view=diff&rev=368552&r1=368551&r2=368552
==============================================================================
--- team/mjordan/manager-events/main/xmldoc.c (original)
+++ team/mjordan/manager-events/main/xmldoc.c Tue Jun 5 11:32:17 2012
@@ -30,10 +30,14 @@
#include "asterisk/_private.h"
#include "asterisk/paths.h"
#include "asterisk/linkedlists.h"
-#include "asterisk/strings.h"
#include "asterisk/config.h"
#include "asterisk/term.h"
+#include "asterisk/astobj2.h"
#include "asterisk/xmldoc.h"
+
+#ifndef AST_XML_DOCS
+#define AST_XML_DOCS 1
+#endif
#ifdef AST_XML_DOCS
@@ -1039,13 +1043,14 @@
}
/*! \internal
- * \brief Generate an AMI action syntax.
- * \param fixnode The manager action node pointer.
- * \param name The name of the manager action.
+ * \brief Generate an AMI action/event syntax.
+ * \param fixnode The manager action/event node pointer.
+ * \param name The name of the manager action/event.
+ * \param manager_type "Action" or "Event"
* \retval The generated syntax.
* \retval NULL on error.
*/
-static char *xmldoc_get_syntax_manager(struct ast_xml_node *fixnode, const char *name)
+static char *xmldoc_get_syntax_manager(struct ast_xml_node *fixnode, const char *name, const char *manager_type)
{
struct ast_str *syntax;
struct ast_xml_node *node = fixnode;
@@ -1058,7 +1063,7 @@
return ast_strdup(name);
}
- ast_str_append(&syntax, 0, "Action: %s", name);
+ ast_str_append(&syntax, 0, "%s: %s", manager_type, name);
for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
if (strcasecmp(ast_xml_node_get_name(node), "parameter")) {
@@ -1107,11 +1112,11 @@
const char *type;
enum syntaxtype stxtype;
} stxtype[] = {
- { "function", FUNCTION_SYNTAX },
- { "application", FUNCTION_SYNTAX },
- { "manager", MANAGER_SYNTAX },
- { "managerEvent", MANAGER_EVENT_SYNTAX },
- { "agi", COMMAND_SYNTAX }
+ { "function", FUNCTION_SYNTAX },
+ { "application", FUNCTION_SYNTAX },
+ { "manager", MANAGER_SYNTAX },
+ { "managerEventInstance", MANAGER_EVENT_SYNTAX },
+ { "agi", COMMAND_SYNTAX }
};
/*! \internal
@@ -1131,6 +1136,30 @@
return FUNCTION_SYNTAX;
}
+static char *_ast_xmldoc_build_syntax(struct ast_xml_node *node, const char *type, const char *name)
+{
+ char *syntax;
+
+ switch (xmldoc_get_syntax_type(type)) {
+ case FUNCTION_SYNTAX:
+ syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
+ break;
+ case COMMAND_SYNTAX:
+ syntax = xmldoc_get_syntax_cmd(node, name, 1);
+ break;
+ case MANAGER_SYNTAX:
+ syntax = xmldoc_get_syntax_manager(node, name, "Action");
+ break;
+ case MANAGER_EVENT_SYNTAX:
+ syntax = xmldoc_get_syntax_manager(node, name, "Event");
+ break;
+ default:
+ syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
+ }
+
+ return syntax;
+}
+
char *ast_xmldoc_build_syntax(const char *type, const char *name, const char *module)
{
struct ast_xml_node *node;
@@ -1148,19 +1177,7 @@
}
if (node) {
- switch (xmldoc_get_syntax_type(type)) {
- case FUNCTION_SYNTAX:
- syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
- break;
- case COMMAND_SYNTAX:
- syntax = xmldoc_get_syntax_cmd(node, name, 1);
- break;
- case MANAGER_SYNTAX:
- syntax = xmldoc_get_syntax_manager(node, name);
- break;
- default:
- syntax = xmldoc_get_syntax_fun(node, name, "parameter", 1, 1);
- }
+ syntax = _ast_xmldoc_build_syntax(node, type, name);
}
return syntax;
}
@@ -1437,24 +1454,13 @@
return ret;
}
-char *ast_xmldoc_build_seealso(const char *type, const char *name, const char *module)
-{
+static char *_ast_xmldoc_build_seealso(struct ast_xml_node *node)
+{
+ char *output;
struct ast_str *outputstr;
- char *output;
- struct ast_xml_node *node;
const char *typename;
const char *content;
int first = 1;
-
- if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
- return NULL;
- }
-
- /* get the application/function root node. */
- node = xmldoc_get_node(type, name, module, documentation_language);
- if (!node || !ast_xml_node_get_children(node)) {
- return NULL;
- }
/* Find the <see-also> node. */
for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
@@ -1506,6 +1512,26 @@
output = ast_strdup(ast_str_buffer(outputstr));
ast_free(outputstr);
+
+ return output;
+}
+
+char *ast_xmldoc_build_seealso(const char *type, const char *name, const char *module)
+{
+ char *output;
+ struct ast_xml_node *node;
+
+ if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
+ return NULL;
+ }
+
+ /* get the application/function root node. */
+ node = xmldoc_get_node(type, name, module, documentation_language);
+ if (!node || !ast_xml_node_get_children(node)) {
+ return NULL;
+ }
+
+ output = _ast_xmldoc_build_seealso(node);
return output;
}
@@ -1736,21 +1762,13 @@
ast_free(internaltabs);
}
-char *ast_xmldoc_build_arguments(const char *type, const char *name, const char *module)
-{
- struct ast_xml_node *node;
- struct ast_str *ret = ast_str_create(128);
+static char *_ast_xmldoc_build_arguments(struct ast_xml_node *node)
+{
char *retstr = NULL;
-
- if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
- ast_free(ret);
- return NULL;
- }
-
- node = xmldoc_get_node(type, name, module, documentation_language);
-
- if (!node || !ast_xml_node_get_children(node)) {
- ast_free(ret);
+ struct ast_str *ret;
+
+ ret = ast_str_create(128);
+ if (!ret) {
return NULL;
}
@@ -1782,6 +1800,23 @@
ast_free(ret);
return retstr;
+}
+
+char *ast_xmldoc_build_arguments(const char *type, const char *name, const char *module)
+{
+ struct ast_xml_node *node;
+
+ if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
+ return NULL;
+ }
+
+ node = xmldoc_get_node(type, name, module, documentation_language);
+
+ if (!node || !ast_xml_node_get_children(node)) {
+ return NULL;
+ }
+
+ return _ast_xmldoc_build_arguments(node);
}
/*! \internal
@@ -1826,6 +1861,35 @@
}
/*!
+ * \brief Get the content of a field (synopsis, description, etc) from an asterisk document tree node
+ * \param node The node to obtain the information from
+ * \param var Name of field to return (synopsis, description, etc).
+ * \param raw Field only contains text, no other elements inside it.
+ * \retval NULL On error.
+ * \retval Field text content on success.
+ */
+static char *_xmldoc_build_field(struct ast_xml_node *node, const char *var, int raw)
+{
+ char *ret = NULL;
+ struct ast_str *formatted;
+
+ node = ast_xml_find_element(ast_xml_node_get_children(node), var, NULL, NULL);
+
+ if (!node || !ast_xml_node_get_children(node)) {
+ ast_debug(1, "Cannot find variable '%s' in tree\n", var);
+ return ret;
+ }
+
+ formatted = xmldoc_get_formatted(node, raw, raw);
+ if (ast_str_strlen(formatted) > 0) {
+ ret = ast_strdup(ast_str_buffer(formatted));
+ }
+ ast_free(formatted);
+
+ return ret;
+}
+
+/*!
* \brief Get the content of a field (synopsis, description, etc) from an asterisk document tree
* \param type Type of element (application, function, ...).
* \param name Name of element (Dial, Echo, Playback, ...).
@@ -1837,35 +1901,25 @@
static char *xmldoc_build_field(const char *type, const char *name, const char *module, const char *var, int raw)
{
struct ast_xml_node *node;
- char *ret = NULL;
- struct ast_str *formatted;
if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
ast_log(LOG_ERROR, "Tried to look in XML tree with faulty values.\n");
- return ret;
+ return NULL;
}
node = xmldoc_get_node(type, name, module, documentation_language);
if (!node) {
ast_log(LOG_WARNING, "Couldn't find %s %s in XML documentation\n", type, name);
- return ret;
- }
-
- node = ast_xml_find_element(ast_xml_node_get_children(node), var, NULL, NULL);
-
- if (!node || !ast_xml_node_get_children(node)) {
- ast_debug(1, "Cannot find variable '%s' in tree '%s'\n", var, name);
- return ret;
- }
-
- formatted = xmldoc_get_formatted(node, raw, raw);
- if (ast_str_strlen(formatted) > 0) {
- ret = ast_strdup(ast_str_buffer(formatted));
- }
- ast_free(formatted);
-
- return ret;
+ return NULL;
+ }
+
+ return _xmldoc_build_field(node, var, raw);
+}
+
+static char *_ast_xmldoc_build_synopsis(struct ast_xml_node *node)
+{
+ return _xmldoc_build_field(node, "synopsis", 1);
}
char *ast_xmldoc_build_synopsis(const char *type, const char *name, const char *module)
@@ -1873,14 +1927,19 @@
return xmldoc_build_field(type, name, module, "synopsis", 1);
}
+static char *_ast_xmldoc_build_description(struct ast_xml_node *node)
+{
+ return _xmldoc_build_field(node, "description", 0);
+}
+
char *ast_xmldoc_build_description(const char *type, const char *name, const char *module)
{
return xmldoc_build_field(type, name, module, "description", 0);
}
-static void ast_xml_doc_destructor(void *obj)
-{
- struct ast_xml_doc *doc = obj;
+static void ast_xml_doc_item_destructor(void *obj)
+{
+ struct ast_xml_doc_item *doc = obj;
if (!doc) {
return;
@@ -1891,47 +1950,159 @@
ast_free(doc->arguments);
ast_free(doc->synopsis);
ast_free(doc->description);
- ast_string_field_free(doc);
-}
-
-static struct ast_xml_doc *ast_xml_doc_alloc(const char *name, const char *type)
-{
- struct ast_xml_doc *doc;
-
- if (!(doc = ao2_alloc(sizeof(*doc), ast_xml_doc_destructor))) {
- ast_log(AST_LOG_ERROR, "Failed to allocate memory for ast_xml_doc instance\n");
- return;
- }
-
- if ( !(doc->syntax = ast_str_alloc(128))
- || !(doc->seealso = ast_str_alloc(128))
- || !(doc->arguments = ast_str_alloc(128))
- || !(doc->synopsis = ast_str_alloc(128))
- || !(doc->description = ast_str_alloc(128))) {
- ast_log(AST_LOG_ERROR, "Failed to allocate strings for ast_xml_doc instance\n");
- goto ast_xml_doc_failure;
- }
-
- if (!ast_string_field_init(doc, 64)) {
- ast_log(AST_LOG_ERROR, "Failed to initialize string field for ast_xml_doc instance\n");
- goto ast_xml_doc_failure;
- }
- ast_string_field_set(doc, name, name);
- ast_string_field_set(doc, type, type);
-
- return doc;
-
-ast_xml_doc_failure:
- ao2_ref(doc, -1);
+ ast_string_field_free_memory(doc);
+
+ if (doc->next) {
+ ao2_ref(doc->next, -1);
+ doc->next = NULL;
+ }
+}
+
+static struct ast_xml_doc_item *ast_xml_doc_item_alloc(const char *name, const char *type)
+{
+ struct ast_xml_doc_item *item;
+
+ if (!(item = ao2_alloc(sizeof(*item), ast_xml_doc_item_destructor))) {
+ ast_log(AST_LOG_ERROR, "Failed to allocate memory for ast_xml_doc_item instance\n");
+ return NULL;
+ }
+
+ if ( !(item->syntax = ast_str_create(128))
+ || !(item->seealso = ast_str_create(128))
+ || !(item->arguments = ast_str_create(128))
+ || !(item->synopsis = ast_str_create(128))
+ || !(item->description = ast_str_create(128))) {
+ ast_log(AST_LOG_ERROR, "Failed to allocate strings for ast_xml_doc_item instance\n");
+ goto ast_xml_doc_item_failure;
+ }
+
+ if (!ast_string_field_init(item, 64)) {
+ ast_log(AST_LOG_ERROR, "Failed to initialize string field for ast_xml_doc_item instance\n");
+ goto ast_xml_doc_item_failure;
+ }
+ ast_string_field_set(item, name, name);
+ ast_string_field_set(item, type, type);
+
+ return item;
+
+ast_xml_doc_item_failure:
+ ao2_ref(item, -1);
return NULL;
}
+static int ast_xml_doc_item_hash(const void *obj, const int flags)
+{
+ const struct ast_xml_doc_item *item = obj;
+ const char *name = (flags & OBJ_KEY) ? obj : item->name;
+ return ast_str_case_hash(name);
+}
+
+static int ast_xml_doc_item_cmp(void *obj, void *arg, int flags)
+{
+ struct ast_xml_doc_item *left = obj;
+ struct ast_xml_doc_item *right = arg;
+ const char *match = (flags & OBJ_KEY) ? arg : right->name;
+ return strcasecmp(left->name, match) ? 0 : (CMP_MATCH | CMP_STOP);
+}
+
+static struct ast_xml_doc_item *xmldoc_build_documentation_item(struct ast_xml_node *node, const char *name, const char *type)
+{
+ struct ast_xml_doc_item *item;
+ char *syntax;
+ char *seealso;
+ char *arguments;
+ char *synopsis;
+ char *description;
+
+ if (!(item = ast_xml_doc_item_alloc(name, type))) {
+ return NULL;
+ }
+
+ syntax = _ast_xmldoc_build_syntax(node, type, name);
+ seealso = _ast_xmldoc_build_seealso(node);
+ arguments = _ast_xmldoc_build_arguments(node);
+ synopsis = _ast_xmldoc_build_synopsis(node);
+ description = _ast_xmldoc_build_description(node);
+
+ ast_str_set(&item->syntax, 0, "%s", syntax);
+ ast_str_set(&item->seealso, 0, "%s", seealso);
+ ast_str_set(&item->arguments, 0, "%s", arguments);
+ ast_str_set(&item->synopsis, 0, "%s", synopsis);
+ ast_str_set(&item->description, 0, "%s", description);
+
+ ast_free(syntax);
+ ast_free(seealso);
+ ast_free(arguments);
+ ast_free(synopsis);
+ ast_free(description);
+
+ return item;
+}
struct ao2_container *ast_xmldoc_build_documentation(const char *type)
{
struct ao2_container *docs;
-
-
+ struct ast_xml_doc_item *item = NULL, *root = NULL;
+ struct ast_xml_node *node = NULL, *instance = NULL;
+ struct documentation_tree *doctree;
+ const char *name;
+
+
+
+ if (!(docs = ao2_container_alloc(127, ast_xml_doc_item_hash, ast_xml_doc_item_cmp))) {
+ ast_log(AST_LOG_ERROR, "Failed to create container for xml document item instances\n");
+ return NULL;
+ }
+
+ AST_RWLIST_RDLOCK(&xmldoc_tree);
+ AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {
+ /* the core xml documents have priority over thirdparty document. */
+ node = ast_xml_get_root(doctree->doc);
+ if (!node) {
+ break;
+ }
+
+ for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
+ /* Ignore empty nodes or nodes that aren't of the type requested */
+ if (!ast_xml_node_get_children(node) || !strcasecmp(ast_xml_node_get_name(node), type)) {
+ continue;
+ }
+
+ name = ast_xml_get_attribute(node, "name");
+
+ switch (xmldoc_get_syntax_type(type)) {
+ case MANAGER_EVENT_SYNTAX:
+ for (instance = ast_xml_node_get_children(node); instance; instance = ast_xml_node_get_next(instance)) {
+ struct ast_xml_doc_item *temp;
+ if (!ast_xml_node_get_children(instance) || strcasecmp(ast_xml_node_get_name(node), "managerEventInstance")) {
+ continue;
+ }
+ temp = xmldoc_build_documentation_item(instance, name, type);
+ if (!temp) {
+ break;
+ }
+ if (!item) {
+ item = temp;
+ root = item;
+ } else {
+ item->next = temp;
+ item = temp;
+ }
+ }
+ item = root;
+ break;
+ default:
+ item = xmldoc_build_documentation_item(node, name, type);
+ }
+
+ if (item) {
+ ao2_link(docs, item);
+ }
+ }
+ }
+ AST_RWLIST_UNLOCK(&xmldoc_tree);
+
+ return docs;
}
#if !defined(HAVE_GLOB_NOMAGIC) || !defined(HAVE_GLOB_BRACE) || defined(DEBUG_NONGNU)
More information about the asterisk-commits
mailing list