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, 43 insertions, 20 deletions

diff --git a/apps/app_playback.c b/apps/app_playback.c
index 4e6c3f530..63dd30857 100644
--- a/apps/app_playback.c
+++ b/apps/app_playback.c
@@ -39,26 +39,49 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 #include "asterisk/say.h"	/* provides config-file based 'say' functions */
 #include "asterisk/cli.h"
 
-static char *app = "Playback";
-
-static char *synopsis = "Play a file";
-
-static char *descrip = 
-"  Playback(filename[&filename2...][,option]):  Plays back given filenames (do not put\n"
-"extension). Options may also be included following a comma.\n"
-"The 'skip' option causes the playback of the message to be skipped if the channel\n"
-"is not in the 'up' state (i.e. it hasn't been  answered  yet). If 'skip' is \n"
-"specified, the application will return immediately should the channel not be\n"
-"off hook.  Otherwise, unless 'noanswer' is specified, the channel will\n"
-"be answered before the sound is played. Not all channels support playing\n"
-"messages while still on hook.\n"
-"This application sets the following channel variable upon completion:\n"
-" PLAYBACKSTATUS    The status of the playback attempt as a text string, one of\n"
-"               SUCCESS | FAILED\n"
-"See Also: Background (application) -- for playing soundfiles that are interruptible\n"
-"          WaitExten (application) -- wait for digits from caller, optionally play music on hold\n"
-;
+/*** DOCUMENTATION
+	<application name="Playback" language="en_US">
+		<synopsis>
+			Play a file.
+		</synopsis>
+		<syntax>
+			<parameter name="filenames" required="true" argsep="&amp;">
+				<argument name="filename" required="true" />
+				<argument name="filename2" multiple="true" />
+			</parameter>
+			<parameter name="options">
+				<para>Comma separated list of options</para>
+				<optionlist>
+					<option name="skip">
+						<para>Do not play if not answered</para>
+					</option>
+					<option name="noanswer">
+						<para>Playback without answering, otherwise the channel will
+						be answered before the sound is played.</para>
+						<note><para>Not all channel types support playing messages while still on hook.</para></note>
+					</option>
+				</optionlist>
+			</parameter>
+		</syntax>
+		<description>
+			<para>Plays back given filenames (do not put extension of wav/alaw etc).
+			The playback command answer the channel if no options are specified.
+			If the file is non-existant it will fail</para>
+			<para>This application sets the following channel variable upon completion:</para>
+			<variablelist>
+				<variable name="PLAYBACKSTATUS">
+					<para>The status of the playback attempt as a text string.</para>
+					<value name="SUCCESS"/>
+					<value name="FAILED"/>
+				</variable>
+			</variablelist>
+			<para>See Also: Background (application) -- for playing soundfiles that are interruptible</para>
+			<para>WaitExten (application) -- wait for digits from caller, optionally play music on hold</para>
+		</description>
+	</application>
+ ***/
 
+static char *app = "Playback";
 
 static struct ast_config *say_cfg = NULL;
 /* save the say' api calls.
@@ -520,7 +543,7 @@ static int load_module(void)
 	}
 
 	ast_cli_register_multiple(cli_playback, sizeof(cli_playback) / sizeof(struct ast_cli_entry));
-	return ast_register_application(app, playback_exec, synopsis, descrip);
+	return ast_register_application_xml(app, playback_exec);
 }
 
 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_DEFAULT, "Sound File Playback Application",