Merge changes from team/group/appdocsxml

This commit introduces the first phase of an effort to manage documentation of the
interfaces in Asterisk in an XML format.  Currently, a new format is available for
applications and dialplan functions.  A good number of conversions to the new format
are also included.

For more information, see the following message to asterisk-dev:

http://lists.digium.com/pipermail/asterisk-dev/2008-October/034968.html


git-svn-id: http://svn.digium.com/svn/asterisk/trunk@153365 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 127 insertions, 36 deletions

diff --git a/funcs/func_cdr.c b/funcs/func_cdr.c
index 9b73d03f1..6c80e4f93 100644
--- a/funcs/func_cdr.c
+++ b/funcs/func_cdr.c
@@ -36,6 +36,133 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 #include "asterisk/app.h"
 #include "asterisk/cdr.h"
 
+/*** DOCUMENTATION
+	<function name="CDR" language="en_US">
+		<synopsis>
+			Gets or sets a CDR variable.
+		</synopsis>	
+		<syntax>
+			<parameter name="name" required="true">
+				<para>CDR field name:</para>
+				<enumlist>
+					<enum name="clid">
+						<para>Caller ID.</para>
+					</enum>
+					<enum name="lastdata">
+						<para>Last application arguments.</para>
+					</enum>
+					<enum name="disposition">
+						<para>ANSWERED, NO ANSWER, BUSY.</para>
+					</enum>
+					<enum name="src">
+						<para>Source.</para>
+					</enum>
+					<enum name="start">
+						<para>Time the call started.</para>
+					</enum>
+					<enum name="amaflags">
+						<para>DOCUMENTATION, BILL, IGNORE, etc.</para>
+					</enum>
+					<enum name="dst">
+						<para>Destination.</para>
+					</enum>
+					<enum name="answer">
+						<para>Time the call was answered.</para>
+					</enum>
+					<enum name="accountcode">
+						<para>The channel's account code.</para>
+					</enum>
+					<enum name="dcontext">
+						<para>Destination context.</para>
+					</enum>
+					<enum name="end">
+						<para>Time the call ended.</para>
+					</enum>
+					<enum name="uniqueid">
+						<para>The channel's unique id.</para>
+					</enum>
+					<enum name="dstchannel">
+						<para>Destination channel.</para>
+					</enum>
+					<enum name="duration">
+						<para>Duration of the call.</para>
+					</enum>
+					<enum name="userfield">
+						<para>The channel's user specified field.</para>
+					</enum>
+					<enum name="lastapp">
+						<para>Last application.</para>
+					</enum>
+					<enum name="billsec">
+						<para>Duration of the call once it was answered.</para>
+					</enum>
+					<enum name="channel">
+						<para>Channel name.</para>
+					</enum>
+				</enumlist>
+			</parameter>
+			<parameter name="options" required="false">
+				<optionlist>
+					<option name="l">
+						<para>Uses the most recent CDR on a channel with multiple records</para>
+					</option>
+					<option name="r">
+						<para>Searches the entire stack of CDRs on the channel.</para>
+					</option>
+					<option name="s">
+						<para>Skips any CDR's that are marked 'LOCKED' due to forkCDR() calls.
+						(on setting/writing CDR vars only)</para>
+					</option>
+					<option name="u">
+						<para>Retrieves the raw, unprocessed value.</para>
+						<para>For example, 'start', 'answer', and 'end' will be retrieved as epoch
+						values, when the <literal>u</literal> option is passed, but formatted as YYYY-MM-DD HH:MM:SS
+						otherwise.  Similarly, disposition and amaflags will return their raw
+						integral values.</para>
+					</option>
+				</optionlist>
+			</parameter>
+		</syntax>
+		<description>
+			<para>All of the CDR field names are read-only, except for <literal>accountcode</literal>,
+			<literal>userfield</literal>, and <literal>amaflags</literal>. You may, however, supply
+			a name not on the above list, and create your own variable, whose value can be changed
+			with this function, and this variable will be stored on the cdr.</para>
+			<note><para>For setting CDR values, the <literal>l</literal> flag does not apply to
+			setting the <literal>accountcode</literal>, <literal>userfield</literal>, or
+			<literal>amaflags</literal>.</para></note>
+			<para>Raw values for <literal>disposition</literal>:</para>
+			<enumlist>
+				<enum name="1">
+					<para>NO ANSWER</para>
+				</enum>
+				<enum name="2">
+					<para>BUSY</para>
+				</enum>
+				<enum name="3">
+					<para>FAILED</para>
+				</enum>
+				<enum name="4">
+					<para>ANSWERED</para>
+				</enum>
+			</enumlist>
+			<para>Raw values for <literal>amaflags</literal>:</para>
+			<enumlist>
+				<enum name="1">
+					<para>OMIT</para>
+				</enum>
+				<enum name="2">
+					<para>BILLING</para>
+				</enum>
+				<enum name="3">
+					<para>DOCUMENTATION</para>
+				</enum>
+			</enumlist>
+			<para>Example: exten => 1,1,Set(CDR(userfield)=test)</para>
+		</description>
+	</function>
+ ***/
+
 enum {
 	OPT_RECURSIVE = (1 << 0),
 	OPT_UNPARSED = (1 << 1),
@@ -128,44 +255,8 @@ static int cdr_write(struct ast_channel *chan, const char *cmd, char *parse,
 
 static struct ast_custom_function cdr_function = {
 	.name = "CDR",
-	.synopsis = "Gets or sets a CDR variable",
-	.syntax = "CDR(<name>[,options])",
 	.read = cdr_read,
 	.write = cdr_write,
-	.desc =
-"Options:\n"
-"  'l' uses the most recent CDR on a channel with multiple records\n"
-"  'r' searches the entire stack of CDRs on the channel\n"
-"  's' skips any CDR's that are marked 'LOCKED' due to forkCDR() calls.\n"
-"      (on setting/writing CDR vars only)\n"
-"  'u' retrieves the raw, unprocessed value\n"
-"  For example, 'start', 'answer', and 'end' will be retrieved as epoch\n"
-"  values, when the 'u' option is passed, but formatted as YYYY-MM-DD HH:MM:SS\n"
-"  otherwise.  Similarly, disposition and amaflags will return their raw\n"
-"  integral values.\n"
-"  Here is a list of all the available cdr field names:\n"
-"    clid          lastdata       disposition\n"
-"    src           start          amaflags\n"
-"    dst           answer         accountcode\n"
-"    dcontext      end            uniqueid\n"
-"    dstchannel    duration       userfield\n"
-"    lastapp       billsec        channel\n"
-"  All of the above variables are read-only, except for accountcode,\n"
-"  userfield, and amaflags. You may, however,  supply\n"
-"  a name not on the above list, and create your own\n"
-"  variable, whose value can be changed with this function,\n"
-"  and this variable will be stored on the cdr.\n"
-"  For setting CDR values, the 'l' flag does not apply to\n"
-"  setting the accountcode, userfield, or amaflags.\n"
-"   raw values for disposition:\n"
-"       1 = NO ANSWER\n"
-"       2 = BUSY\n"
-"       3 = FAILED\n"
-"       4 = ANSWERED\n"
-"    raw values for amaflags:\n"
-"       1 = OMIT\n"
-"       2 = BILLING\n"
-"       3 = DOCUMENTATION\n",
 };
 
 static int unload_module(void)