Add the ability to specify technology specific documentation

A number of applications/AMI commands in Asterisk have specific behavioral
differences depending on the resource or channel technology those
applications are executed on.  For example, the MessageSend application/
command is technology agnostic, but how the channel drivers that support
that functionality behave is dependant on the protocols and channel
driver implementation.  Prior to this patch, those details were either
documented in the application/command documentation itself, or were left
undocumented.

This patch adds a new element to the documentation schema, <info/>.  An info
node is essentially a piece of technology specific reference information that
can be included by any top level XML documentation node.  For example, the
MessageSend application can now include XMPP/SIP specific information, where
that technology specific information can be defined in chan_motif/res_xmpp/
chan_sip.  Likewise, that information can also be included in the MessageSend
AMI command.

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




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

5 files changed, 127 insertions, 40 deletions

diff --git a/channels/chan_sip.c b/channels/chan_sip.c
index eadf9b961..9d57ad5bd 100644
--- a/channels/chan_sip.c
+++ b/channels/chan_sip.c
@@ -572,6 +572,14 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			via multiple <literal>Variable: name=value</literal> sequences.</para>
 		</description>
 	</manager>
+	<info name="SIPMessageFromInfo" language="en_US" tech="SIP">
+		<para>The <literal>from</literal> parameter can be a configured peer name
+		or in the form of "display-name" &lt;URI&gt;.</para>
+	</info>
+	<info name="SIPMessageToInfo" language="en_US" tech="SIP">
+		<para>Specifying a prefix of <literal>sip:</literal> will send the
+		message as a SIP MESSAGE request.</para>
+	</info>
  ***/
 
 static int min_expiry = DEFAULT_MIN_EXPIRY;        /*!< Minimum accepted registration time */
diff --git a/doc/appdocsxml.dtd b/doc/appdocsxml.dtd
index d5815648e..456ac188f 100644
--- a/doc/appdocsxml.dtd
+++ b/doc/appdocsxml.dtd
@@ -1,4 +1,4 @@
-  <!ELEMENT docs (application|function|agi|manager|managerEvent)*>
+  <!ELEMENT docs (application|function|agi|manager|managerEvent|info)*>
   <!ATTLIST docs xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude">
 
   <!ELEMENT xi:include (xi:fallback?) >
@@ -36,6 +36,11 @@
   <!ELEMENT managerEventInstance (synopsis?,syntax?,description?,see-also?)*>
   <!ATTLIST managerEventInstance class CDATA #REQUIRED>
 
+  <!ELEMENT info (para|note|warning|variablelist|enumlist|info|xi:include)*>
+  <!ATTLIST info name CDATA #REQUIRED>
+  <!ATTLIST info language CDATA #REQUIRED>
+  <!ATTLIST info tech CDATA #REQUIRED>
+
   <!ELEMENT see-also (ref|xi:include)*>
 
   <!ELEMENT ref (#PCDATA)>
@@ -46,9 +51,9 @@
   <!ELEMENT syntax (parameter|xi:include)*>
   <!ATTLIST syntax argsep CDATA ",">
 
-  <!ELEMENT description (para|note|warning|variablelist|enumlist|xi:include)*>
+  <!ELEMENT description (para|note|warning|variablelist|enumlist|info|xi:include)*>
 
-  <!ELEMENT parameter (optionlist|enumlist|argument|para|note|warning|parameter|xi:include)*>
+  <!ELEMENT parameter (optionlist|enumlist|argument|para|note|warning|parameter|info|xi:include)*>
   <!ATTLIST parameter name CDATA "">
   <!ATTLIST parameter required (yes|no|true|false) "false">
   <!ATTLIST parameter multiple (yes|no|true|false) "false">
@@ -58,17 +63,17 @@
   <!ATTLIST parameter argsep CDATA ",">
 
   <!ELEMENT optionlist (option+)>
-  <!ELEMENT option (argument|para|note|warning|variablelist|enumlist|xi:include)*>
+  <!ELEMENT option (argument|para|note|warning|variablelist|enumlist|info|xi:include)*>
   <!ATTLIST option name CDATA #REQUIRED>
   <!ATTLIST option argsep CDATA ",">
   <!ATTLIST option implies CDATA "">
   <!ATTLIST option hasparams CDATA "">
 
   <!ELEMENT enumlist (enum+)>
-  <!ELEMENT enum (para|note|warning|parameter|enumlist|xi:include)*>
+  <!ELEMENT enum (para|note|warning|parameter|enumlist|info|xi:include)*>
   <!ATTLIST enum name CDATA "">
 
-  <!ELEMENT argument (para|note|warning|variablelist|argument|xi:include)*>
+  <!ELEMENT argument (para|note|warning|variablelist|argument|info|xi:include)*>
   <!ATTLIST argument name CDATA #REQUIRED>
   <!ATTLIST argument multiple (yes|no|true|false) "false">
   <!ATTLIST argument required (yes|no|true|false) "false">
@@ -87,7 +92,7 @@
   <!ELEMENT warning (para+|xi:include*)>
 
   <!ELEMENT variablelist (variable+|xi:include*)>
-  <!ELEMENT variable (#PCDATA|value|para|xi:include)*>
+  <!ELEMENT variable (#PCDATA|value|para|info|xi:include)*>
   <!ATTLIST variable name CDATA "">
 
   <!ELEMENT value (#PCDATA)>
diff --git a/main/message.c b/main/message.c
index b79ec0d6b..1ac9231e3 100644
--- a/main/message.c
+++ b/main/message.c
@@ -122,20 +122,20 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		<syntax>
 			<parameter name="to" required="true">
 				<para>A To URI for the message.</para>
+				<xi:include xpointer="xpointer(/docs/info[@name='SIPMessageToInfo'])" />
+				<xi:include xpointer="xpointer(/docs/info[@name='XMPPMessageToInfo'])" />
 			</parameter>
 			<parameter name="from" required="false">
 				<para>A From URI for the message if needed for the
 				message technology being used to send this message.</para>
-				<note>
-					<para>For SIP the from parameter can be a configured peer name
-					or in the form of "display-name" &lt;URI&gt;.</para>
-				</note>
+				<xi:include xpointer="xpointer(/docs/info[@name='SIPMessageFromInfo'])" />
 			</parameter>
 		</syntax>
 		<description>
 			<para>Send a text message.  The body of the message that will be
-			sent is what is currently set to <literal>MESSAGE(body)</literal>.</para>
-
+			sent is what is currently set to <literal>MESSAGE(body)</literal>.
+			  The technology chosen for sending the message is determined
+			based on a prefix to the <literal>to</literal> parameter.</para>
 			<para>This application sets the following channel variables:</para>
 			<variablelist>
 				<variable name="MESSAGE_SEND_STATUS">
@@ -164,14 +164,13 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			<xi:include xpointer="xpointer(/docs/manager[@name='Login']/syntax/parameter[@name='ActionID'])" />
 			<parameter name="To" required="true">
 				<para>The URI the message is to be sent to.</para>
+				<xi:include xpointer="xpointer(/docs/info[@name='SIPMessageToInfo'])" />
+				<xi:include xpointer="xpointer(/docs/info[@name='XMPPMessageToInfo'])" />
 			</parameter>
 			<parameter name="From">
 				<para>A From URI for the message if needed for the
 				message technology being used to send this message.</para>
-				<note>
-					<para>For SIP the from parameter can be a configured peer name
-					or in the form of "display-name" &lt;URI&gt;.</para>
-				</note>
+				<xi:include xpointer="xpointer(/docs/info[@name='SIPMessageFromInfo'])" />
 			</parameter>
 			<parameter name="Body">
 				<para>The message body text.  This must not contain any newlines as that
diff --git a/main/xmldoc.c b/main/xmldoc.c
index 631444431..e8383511e 100644
--- a/main/xmldoc.c
+++ b/main/xmldoc.c
@@ -65,6 +65,10 @@ struct documentation_tree {
 
 static char *xmldoc_get_syntax_cmd(struct ast_xml_node *fixnode, const char *name, int printname);
 static int xmldoc_parse_enumlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer);
+static int xmldoc_parse_info(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer);
+static int xmldoc_parse_para(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer);
+static int xmldoc_parse_specialtags(struct ast_xml_node *fixnode, const char *tabs, const char *posttabs, struct ast_str **buffer);
+
 
 /*!
  * \brief Container of documentation trees
@@ -1197,6 +1201,26 @@ char *ast_xmldoc_build_syntax(const char *type, const char *name, const char *mo
 }
 
 /*! \internal
+ *  \brief Parse common internal elements.  This includes paragraphs, special
+ *         tags, and information nodes.
+ *  \param node The element to parse
+ *  \param tabs Add this string before the content of the parsed element.
+ *  \param posttabs Add this string after the content of the parsed element.
+ *  \param buffer This must be an already allocated ast_str. It will be used to
+ *                store the result (if something has already been placed in the
+ *                buffer, the parsed elements will be appended)
+ *  \retval 1 if any data was appended to the buffer
+ *  \retval 2 if the data appended to the buffer contained a text paragraph
+ *  \retval 0 if no data was appended to the buffer
+ */
+static int xmldoc_parse_common_elements(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
+{
+	return (xmldoc_parse_para(node, tabs, posttabs, buffer)
+		|| xmldoc_parse_specialtags(node, tabs, posttabs, buffer)
+		|| xmldoc_parse_info(node, tabs, posttabs, buffer));
+}
+
+/*! \internal
  *  \brief Parse a <para> element.
  *  \param node The <para> element pointer.
  *  \param tabs Added this string before the content of the <para> element.
@@ -1287,7 +1311,8 @@ static int xmldoc_parse_specialtags(struct ast_xml_node *fixnode, const char *ta
 		/* parse <para> elements inside special tags. */
 		for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
 			/* first <para> just print it without tabs at the begining. */
-			if (xmldoc_parse_para(node, (!count ? "" : tabs), posttabs, buffer) == 2) {
+			if ((xmldoc_parse_para(node, (!count ? "" : tabs), posttabs, buffer) == 2)
+				|| (xmldoc_parse_info(node, (!count ? "": tabs), posttabs, buffer) == 2)) {
 				ret = 2;
 			}
 		}
@@ -1303,6 +1328,55 @@ static int xmldoc_parse_specialtags(struct ast_xml_node *fixnode, const char *ta
 }
 
 /*! \internal
+ *  \brief Parse an 'info' tag inside an element.
+ *  \param node A pointer to the 'info' xml node.
+ *  \param tabs A string to be appended at the beginning of each line being printed
+ *              inside 'buffer'
+ *  \param posttabs Add this string after the content of the <para> element, if one exists
+ *  \param String buffer to put values found inide the info element.
+ *  \ret 2 if the information contained a para element, and it returned a value of 2
+ *  \ret 1 if information was put into the buffer
+ *  \ret 0 if no information was put into the buffer or error
+ */
+static int xmldoc_parse_info(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
+{
+	const char *tech;
+	char *internaltabs;
+	int internal_ret;
+	int ret = 0;
+
+	if (strcasecmp(ast_xml_node_get_name(node), "info")) {
+		return ret;
+	}
+
+	ast_asprintf(&internaltabs, "%s    ", tabs);
+	if (!internaltabs) {
+		return ret;
+	}
+
+	tech = ast_xml_get_attribute(node, "tech");
+	if (tech) {
+		ast_str_append(buffer, 0, "%s<note>Technology: %s</note>\n", internaltabs, tech);
+		ast_xml_free_attr(tech);
+	}
+
+	ret = 1;
+
+	for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
+		if (!strcasecmp(ast_xml_node_get_name(node), "enumlist")) {
+			xmldoc_parse_enumlist(node, internaltabs, buffer);
+		} else if ((internal_ret = xmldoc_parse_common_elements(node, internaltabs, posttabs, buffer))) {
+			if (internal_ret > ret) {
+				ret = internal_ret;
+			}
+		}
+	}
+	ast_free(internaltabs);
+
+	return ret;
+}
+
+/*! \internal
  *  \brief Parse an <argument> element from the xml documentation.
  *  \param fixnode Pointer to the 'argument' xml node.
  *  \param insideparameter If we are parsing an <argument> inside a <parameter>.
@@ -1327,7 +1401,7 @@ static int xmldoc_parse_argument(struct ast_xml_node *fixnode, int insideparamet
 	if (!argname) {
 		return 0;
 	}
-	if (xmldoc_has_inside(node, "para") || xmldoc_has_specialtags(node)) {
+	if (xmldoc_has_inside(node, "para") || xmldoc_has_inside(node, "info") || xmldoc_has_specialtags(node)) {
 		ast_str_append(buffer, 0, "%s%s%s", tabs, argname, (insideparameter ? "\n" : ""));
 		ast_xml_free_attr(argname);
 	} else {
@@ -1336,10 +1410,7 @@ static int xmldoc_parse_argument(struct ast_xml_node *fixnode, int insideparamet
 	}
 
 	for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
-		if (xmldoc_parse_para(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2) {
-			count++;
-			ret = 1;
-		} else if (xmldoc_parse_specialtags(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2) {
+		if (xmldoc_parse_common_elements(node, (insideparameter ? paramtabs : (!count ? " - " : tabs)), "\n", buffer) == 2) {
 			count++;
 			ret = 1;
 		}
@@ -1368,10 +1439,7 @@ static int xmldoc_parse_variable(struct ast_xml_node *node, const char *tabs, st
 	int ret = 0, printedpara=0;
 
 	for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
-		if (xmldoc_parse_para(tmp, (ret ? tabs : ""), "\n", buffer)) {
-			printedpara = 1;
-			continue;
-		} else if (xmldoc_parse_specialtags(tmp, (ret ? tabs : ""), "\n", buffer)) {
+		if (xmldoc_parse_common_elements(tmp, (ret ? tabs : ""), "\n", buffer)) {
 			printedpara = 1;
 			continue;
 		}
@@ -1442,10 +1510,7 @@ static int xmldoc_parse_variablelist(struct ast_xml_node *node, const char *tabs
 	}
 	for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
 		/* We can have a <para> element inside the variable list */
-		if ((xmldoc_parse_para(tmp, (ret ? tabs : ""), "\n", buffer))) {
-			ret = 1;
-			continue;
-		} else if ((xmldoc_parse_specialtags(tmp, (ret ? tabs : ""), "\n", buffer))) {
+		if (xmldoc_parse_common_elements(tmp, (ret ? tabs : ""), "\n", buffer)) {
 			ret = 1;
 			continue;
 		}
@@ -1579,9 +1644,7 @@ static int xmldoc_parse_enum(struct ast_xml_node *fixnode, const char *tabs, str
 	ast_asprintf(&optiontabs, "%s    ", tabs);
 
 	for (node = ast_xml_node_get_children(node); node; node = ast_xml_node_get_next(node)) {
-		if ((xmldoc_parse_para(node, (ret ? tabs : " - "), "\n", buffer))) {
-			ret = 1;
-		} else if ((xmldoc_parse_specialtags(node, (ret ? tabs : " - "), "\n", buffer))) {
+		if (xmldoc_parse_common_elements(node, (ret ? tabs : " - "), "\n", buffer)) {
 			ret = 1;
 		}
 
@@ -1659,9 +1722,7 @@ static int xmldoc_parse_option(struct ast_xml_node *fixnode, const char *tabs, s
 			continue;
 		}
 
-		if (xmldoc_parse_para(node, (ret ? tabs :  ""), "\n", buffer)) {
-			ret = 1;
-		} else if (xmldoc_parse_specialtags(node, (ret ? tabs :  ""), "\n", buffer)) {
+		if (xmldoc_parse_common_elements(node, (ret ? tabs :  ""), "\n", buffer)) {
 			ret = 1;
 		}
 
@@ -1779,6 +1840,18 @@ static void xmldoc_parse_parameter(struct ast_xml_node *fixnode, const char *tab
 				continue;
 			}
 			continue;
+		} else if (!strcasecmp(ast_xml_node_get_name(node), "info")) {
+			if (!printed) {
+				ast_str_append(buffer, 0, "%s\n", paramname);
+				ast_xml_free_attr(paramname);
+				printed = 1;
+			}
+			if (xmldoc_parse_info(node, internaltabs, "\n", buffer)) {
+				/* If anything ever goes in below this condition before the continue below,
+				 * we should probably continue immediately. */
+				continue;
+			}
+			continue;
 		} else if ((xmldoc_parse_specialtags(node, internaltabs, "\n", buffer))) {
 			continue;
 		}
@@ -1881,9 +1954,7 @@ static struct ast_str *xmldoc_get_formatted(struct ast_xml_node *node, int raw_o
 	} else {
 		for (tmp = ast_xml_node_get_children(node); tmp; tmp = ast_xml_node_get_next(tmp)) {
 			/* if found, parse a <para> element. */
-			if (xmldoc_parse_para(tmp, "", "\n", &ret)) {
-				continue;
-			} else if (xmldoc_parse_specialtags(tmp, "", "\n", &ret)) {
+			if (xmldoc_parse_common_elements(tmp, "", "\n", &ret)) {
 				continue;
 			}
 			/* if found, parse a <variablelist> element. */
diff --git a/res/res_xmpp.c b/res/res_xmpp.c
index 643eaa7c2..93916c583 100644
--- a/res/res_xmpp.c
+++ b/res/res_xmpp.c
@@ -270,6 +270,10 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			<para>Sends a message to a Jabber Client.</para>
 		</description>
 	</manager>
+	<info name="XMPPMessageToInfo" language="en_US" tech="XMPP">
+		<para>Specifying a prefix of <literal>xmpp:</literal> will send the
+		message as an XMPP chat message.</para>
+	</info>
 ***/
 
 /*! \brief Supported general configuration flags */