From: Matthew Jordan Date: Thu, 31 Jul 2014 11:49:40 +0000 (+0000) Subject: xmldocs: Add support for an tag in the Asterisk XML Documentation X-Git-Tag: 13.0.0-beta1~56 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=922e3203a9303acbc95a334793a41e07e3f4772d;p=thirdparty%2Fasterisk.git xmldocs: Add support for an tag in the Asterisk XML Documentation This patch adds support for an tag in the XML documentation schema. For CLI help, this doesn't change the formatting too much: - Preceeding white space is removed - Unlike with para elements, new lines are preserved However, having an tag in the XML schema allows for the wiki documentation generation script to surround the documentation with {code} or {noformat} tags, generating much better content for the wiki - and allowing us to put dialplan examples (and other code snippets, if desired) into the documentation for an application/function/AMI command/etc. Review: https://reviewboard.asterisk.org/r/3807/ git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@419822 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- diff --git a/doc/appdocsxml.dtd b/doc/appdocsxml.dtd index 65167d5595..511930fe26 100644 --- a/doc/appdocsxml.dtd +++ b/doc/appdocsxml.dtd @@ -92,7 +92,7 @@ - + @@ -129,6 +129,10 @@ + + + + diff --git a/funcs/func_jitterbuffer.c b/funcs/func_jitterbuffer.c index 31ab86ce31..0b57caf6e4 100644 --- a/funcs/func_jitterbuffer.c +++ b/funcs/func_jitterbuffer.c @@ -66,13 +66,25 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") target_extra: Defaults to 40ms This option only affects the adaptive jitterbuffer. It represents the amount time in milliseconds by which the new jitter buffer will pad its size. - Examples: - exten => 1,1,Set(JITTERBUFFER(fixed)=default);Fixed with defaults. - exten => 1,1,Set(JITTERBUFFER(fixed)=200);Fixed with max size 200ms, default resync threshold and target extra. - exten => 1,1,Set(JITTERBUFFER(fixed)=200,1500);Fixed with max size 200ms resync threshold 1500. - exten => 1,1,Set(JITTERBUFFER(adaptive)=default);Adaptive with defaults. - exten => 1,1,Set(JITTERBUFFER(adaptive)=200,,60);Adaptive with max size 200ms, default resync threshold and 40ms target extra. - exten => 1,n,Set(JITTERBUFFER(disabled)=);Remove previously applied jitterbuffer + + exten => 1,1,Set(JITTERBUFFER(fixed)=default) + + + exten => 1,1,Set(JITTERBUFFER(fixed)=200) + + + exten => 1,1,Set(JITTERBUFFER(fixed)=200,1500) + + + exten => 1,1,Set(JITTERBUFFER(adaptive)=default) + + + exten => 1,1,Set(JITTERBUFFER(adaptive)=200,,60) + + + exten => 1,1,Set(JITTERBUFFER(fixed)=default) + exten => 1,n,Set(JITTERBUFFER(disabled)=) + If a channel specifies a jitterbuffer due to channel driver configuration and the JITTERBUFFER function has set a jitterbuffer for that channel, the jitterbuffer set by the JITTERBUFFER function will take priority and the jitterbuffer set by the channel diff --git a/main/xmldoc.c b/main/xmldoc.c index a84b05982c..50b6cfe7d0 100644 --- a/main/xmldoc.c +++ b/main/xmldoc.c @@ -104,7 +104,9 @@ static const struct strcolorized_tags { /* Special tags */ { "", "", COLOR_YELLOW, "", "" }, - { "", "", COLOR_RED, "", "" } + { "", "", COLOR_RED, "", "" }, + { "", "", COLOR_WHITE, "", "" }, + { "", "", COLOR_GRAY, "", ""}, }; static const struct strspecial_tags { @@ -113,7 +115,8 @@ static const struct strspecial_tags { const char *end; /*!< Print this at the end. */ } special_tags[] = { { "note", "NOTE: ", "" }, - { "warning", "WARNING!!!: ", "" } + { "warning", "WARNING!!!: ", "" }, + { "example", "Example: ", "" }, }; /*! @@ -453,8 +456,9 @@ char *ast_xmldoc_printable(const char *bwinput, int withcolors) * \param text String to be cleaned up. * \param output buffer (not already allocated). * \param lastspaces Remove last spaces in the string. + * \param maintain_newlines Preserve new line characters (\n \r) discovered in the string */ -static void xmldoc_string_cleanup(const char *text, struct ast_str **output, int lastspaces) +static void xmldoc_string_cleanup(const char *text, struct ast_str **output, int lastspaces, int maintain_newlines) { int i; size_t textlen; @@ -474,6 +478,9 @@ static void xmldoc_string_cleanup(const char *text, struct ast_str **output, int for (i = 0; i < textlen; i++) { if (text[i] == '\n' || text[i] == '\r') { + if (maintain_newlines) { + ast_str_append(output, 0, "%c", text[i]); + } /* remove spaces/tabs/\n after a \n. */ while (text[i + 1] == '\t' || text[i + 1] == '\r' || text[i + 1] == '\n') { i++; @@ -1417,7 +1424,7 @@ static int xmldoc_parse_para(struct ast_xml_node *node, const char *tabs, const tmptext = ast_xml_get_text(tmp); if (tmptext) { /* Strip \n etc. */ - xmldoc_string_cleanup(tmptext, &tmpstr, 0); + xmldoc_string_cleanup(tmptext, &tmpstr, 0, 0); ast_xml_free_text(tmptext); if (tmpstr) { if (strcasecmp(ast_xml_node_get_name(tmp), "text")) { @@ -1437,6 +1444,57 @@ static int xmldoc_parse_para(struct ast_xml_node *node, const char *tabs, const return ret; } +/*! + * \internal + * \brief Parse an node. + * \since 13.0.0 + * + * \param fixnode An ast xml pointer to the node. + * \param buffer The output buffer. + * + * \retval 0 if no example node is parsed. + * \retval 1 if an example node is parsed. + */ +static int xmldoc_parse_example(struct ast_xml_node *fixnode, struct ast_str **buffer) +{ + struct ast_xml_node *node = fixnode; + const char *tmptext; + const char *title; + struct ast_str *stripped_text; + int ret = 0; + + if (!node || !ast_xml_node_get_children(node)) { + return ret; + } + + if (strcasecmp(ast_xml_node_get_name(node), "example")) { + return ret; + } + + ret = 1; + + title = ast_xml_get_attribute(node, "title"); + if (title) { + ast_str_append(buffer, 0, "%s", title); + ast_xml_free_attr(title); + } + ast_str_append(buffer, 0, "\n"); + + for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) { + tmptext = ast_xml_get_text(node); + if (tmptext) { + xmldoc_string_cleanup(tmptext, &stripped_text, 0, 1); + if (stripped_text) { + ast_str_append(buffer, 0, "%s\n", ast_str_buffer(stripped_text)); + ast_xml_free_text(tmptext); + ast_free(stripped_text); + } + } + } + + return ret; +} + /*! * \internal * \brief Parse special elements defined in 'struct special_tags' special elements must have a element inside them. @@ -1472,6 +1530,11 @@ static int xmldoc_parse_specialtags(struct ast_xml_node *fixnode, const char *ta ast_str_append(buffer, 0, "%s%s", tabs, special_tags[i].init); } + if (xmldoc_parse_example(node, buffer)) { + ret = 1; + break; + } + /* parse elements inside special tags. */ for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) { /* first just print it without tabs at the begining. */ @@ -1585,7 +1648,7 @@ static int xmldoc_parse_variable(struct ast_xml_node *node, const char *tabs, st /* Check inside this node for any explanation about its meaning. */ if (tmptext) { /* Cleanup text. */ - xmldoc_string_cleanup(tmptext, &cleanstr, 1); + xmldoc_string_cleanup(tmptext, &cleanstr, 1, 0); ast_xml_free_text(tmptext); if (cleanstr && ast_str_strlen(cleanstr) > 0) { ast_str_append(buffer, 0, ":%s", ast_str_buffer(cleanstr)); @@ -2147,18 +2210,24 @@ static struct ast_str *xmldoc_get_formatted(struct ast_xml_node *node, int raw_o /* xmldoc_string_cleanup will allocate the ret object */ notcleanret = ast_xml_get_text(node); tmpstr = notcleanret; - xmldoc_string_cleanup(ast_skip_blanks(notcleanret), &ret, 0); + xmldoc_string_cleanup(ast_skip_blanks(notcleanret), &ret, 0, 0); ast_xml_free_text(tmpstr); } else { ret = ast_str_create(128); for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) { - /* if found, parse a element. */ + /* if found, parse children elements. */ if (xmldoc_parse_common_elements(tmp, "", "\n", &ret)) { continue; } - /* if found, parse a element. */ - xmldoc_parse_variablelist(tmp, "", &ret); - xmldoc_parse_enumlist(tmp, " ", &ret); + if (xmldoc_parse_variablelist(tmp, "", &ret)) { + continue; + } + if (xmldoc_parse_enumlist(tmp, " ", &ret)) { + continue; + } + if (xmldoc_parse_specialtags(tmp, "", "", &ret)) { + continue; + } } /* remove last '\n' */ /* XXX Don't modify ast_str internals manually */