diff options
author | Eliel C. Sardanons <eliels@gmail.com> | 2008-11-03 01:01:25 +0000 |
---|---|---|
committer | Eliel C. Sardanons <eliels@gmail.com> | 2008-11-03 01:01:25 +0000 |
commit | 9167a2b5e164687d4c9a0618a42d0dfe30090b9b (patch) | |
tree | 81df3f713ae7c89cfb8228bf411a5e9eb673293a | |
parent | a67790c6f53e4b002556eca8438dbd56994ea056 (diff) |
Add XML documentation for:
- WaitForSilence()
- WaitForNoise()
- WaitForRing()
- IVRDemo()
- DBDel()
- DBDeltree()
(issue #13699)
Reported by: snuffy
Patches:
bug13699_20081016.diff uploaded by snuffy (license 35)
(With minor changes)
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@153747 65c4cc65-6c06-0410-ace0-fbb531ad65f3
-rw-r--r-- | apps/app_db.c | 50 | ||||
-rw-r--r-- | apps/app_ivrdemo.c | 21 | ||||
-rw-r--r-- | apps/app_waitforring.c | 24 | ||||
-rw-r--r-- | apps/app_waitforsilence.c | 104 |
4 files changed, 140 insertions, 59 deletions
diff --git a/apps/app_db.c b/apps/app_db.c index f141209e9..72b604680 100644 --- a/apps/app_db.c +++ b/apps/app_db.c @@ -39,23 +39,43 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/astdb.h" #include "asterisk/lock.h" -/*! \todo XXX Remove this application after 1.4 is relased */ -static char *d_descrip = -" DBdel(family/key): This application will delete a key from the Asterisk\n" -"database.\n" -" This application has been DEPRECATED in favor of the DB_DELETE function.\n"; - -static char *dt_descrip = -" DBdeltree(family[/keytree]): This application will delete a family or keytree\n" -"from the Asterisk database\n"; +/*** DOCUMENTATION + <application name="DBdel" language="en_US"> + <synopsis> + Delete a key from the asterisk database. + </synopsis> + <syntax argsep="/"> + <parameter name="family" required="true" /> + <parameter name="key" required="true" /> + </syntax> + <description> + <para>This application will delete a <replaceable>key</replaceable> from the Asterisk + database.</para> + <note><para>This application has been DEPRECATED in favor of the DB_DELETE function.</para></note> + </description> + <see-also> + <ref type="function">DB_DELETE</ref> + </see-also> + </application> + <application name="DBdeltree" language="en_US"> + <synopsis> + Delete a family or keytree from the asterisk database. + </synopsis> + <syntax argsep="/"> + <parameter name="family" required="true" /> + <parameter name="keytree" /> + </syntax> + <description> + <para>This application will delete a <replaceable>family</replaceable> or <replaceable>keytree</replaceable> + from the Asterisk database.</para> + </description> + </application> + ***/ +/*! \todo XXX Remove this application after 1.4 is relased */ static char *d_app = "DBdel"; static char *dt_app = "DBdeltree"; -static char *d_synopsis = "Delete a key from the database"; -static char *dt_synopsis = "Delete a family or keytree from the database"; - - static int deltree_exec(struct ast_channel *chan, void *data) { char *argv, *family, *keytree; @@ -130,8 +150,8 @@ static int load_module(void) { int retval; - retval = ast_register_application(d_app, del_exec, d_synopsis, d_descrip); - retval |= ast_register_application(dt_app, deltree_exec, dt_synopsis, dt_descrip); + retval = ast_register_application_xml(d_app, del_exec); + retval |= ast_register_application_xml(dt_app, deltree_exec); return retval; } diff --git a/apps/app_ivrdemo.c b/apps/app_ivrdemo.c index 6dbbe7191..13f4bcc9c 100644 --- a/apps/app_ivrdemo.c +++ b/apps/app_ivrdemo.c @@ -40,11 +40,22 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/lock.h" #include "asterisk/app.h" -static char *tdesc = "IVR Demo Application"; +/*** DOCUMENTATION + <application name="IVRDemo" language="en_US"> + <synopsis> + IVR Demo Application. + </synopsis> + <syntax> + <parameter name="filename" required="true" /> + </syntax> + <description> + <para>This is a skeleton application that shows you the basic structure to create your + own asterisk applications and demonstrates the IVR demo.</para> + </description> + </application> + ***/ + static char *app = "IVRDemo"; -static char *synopsis = -" This is a skeleton application that shows you the basic structure to create your\n" -"own asterisk applications and demonstrates the IVR demo.\n"; static int ivr_demo_func(struct ast_channel *chan, void *data) { @@ -109,7 +120,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, skel_exec, tdesc, synopsis); + return ast_register_application_xml(app, skel_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "IVR Demo Application"); diff --git a/apps/app_waitforring.c b/apps/app_waitforring.c index f2d21e516..fd5913e04 100644 --- a/apps/app_waitforring.c +++ b/apps/app_waitforring.c @@ -35,16 +35,24 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/module.h" #include "asterisk/lock.h" -static char *synopsis = "Wait for Ring Application"; - -static char *desc = " WaitForRing(timeout):\n" -"Returns 0 after waiting at least timeout seconds. and\n" -"only after the next ring has completed. Returns 0 on\n" -"success or -1 on hangup\n"; +/*** DOCUMENTATION + <application name="WaitForRing" language="en_US"> + <synopsis> + Wait for Ring Application. + </synopsis> + <syntax> + <parameter name="timeout" required="true" /> + </syntax> + <description> + <para>Returns <literal>0</literal> after waiting at least <replaceable>timeout</replaceable> seconds, + and only after the next ring has completed. Returns <literal>0</literal> on success or + <literal>-1</literal> on hangup.</para> + </description> + </application> + ***/ static char *app = "WaitForRing"; - static int waitforring_exec(struct ast_channel *chan, void *data) { struct ast_frame *f; @@ -111,7 +119,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, waitforring_exec, synopsis, desc); + return ast_register_application_xml(app, waitforring_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Waits until first ring after time"); diff --git a/apps/app_waitforsilence.c b/apps/app_waitforsilence.c index eedbf15ac..1aa777575 100644 --- a/apps/app_waitforsilence.c +++ b/apps/app_waitforsilence.c @@ -48,37 +48,79 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/dsp.h" #include "asterisk/module.h" -static char *app_silence = "WaitForSilence"; -static char *synopsis_silence = "Waits for a specified amount of silence"; -static char *descrip_silence = -" WaitForSilence(silencerequired[,iterations][,timeout]):\n" -"Wait for Silence: Waits for up to 'silencerequired' \n" -"milliseconds of silence, 'iterations' times or once if omitted.\n" -"An optional timeout specified the number of seconds to return\n" -"after, even if we do not receive the specified amount of silence.\n" -"Use 'timeout' with caution, as it may defeat the purpose of this\n" -"application, which is to wait indefinitely until silence is detected\n" -"on the line. This is particularly useful for reverse-911-type\n" -"call broadcast applications where you need to wait for an answering\n" -"machine to complete its spiel before playing a message.\n" -"The timeout parameter is specified only to avoid an infinite loop in\n" -"cases where silence is never achieved. Typically you will want to\n" -"include two or more calls to WaitForSilence when dealing with an answering\n" -"machine; first waiting for the spiel to finish, then waiting for the beep, etc.\n\n" - "Examples:\n" -" - WaitForSilence(500,2) will wait for 1/2 second of silence, twice\n" -" - WaitForSilence(1000) will wait for 1 second of silence, once\n" -" - WaitForSilence(300,3,10) will wait for 300ms silence, 3 times,\n" -" and returns after 10 sec, even if silence is not detected\n\n" -"Sets the channel variable WAITSTATUS with to one of these values:\n" -"SILENCE - if exited with silence detected\n" -"TIMEOUT - if exited without silence detected after timeout\n"; +/*** DOCUMENTATION + <application name="WaitForSilence" language="en_US"> + <synopsis> + Waits for a specified amount of silence. + </synopsis> + <syntax> + <parameter name="silencerequired" required="true" /> + <parameter name="iterations"> + <para>If not specified, defaults to <literal>1</literal>.</para> + </parameter> + <parameter name="timeout"> + <para>Is specified only to avoid an infinite loop in cases where silence is never achieved.</para> + </parameter> + </syntax> + <description> + <para>Waits for up to <replaceable>silencerequired</replaceable> milliseconds of silence, + <replaceable>iterations</replaceable> times. An optional <replaceable>timeout</replaceable> + specified the number of seconds to return after, even if we do not receive the specified amount of silence. + Use <replaceable>timeout</replaceable> with caution, as it may defeat the purpose of this application, which + is to wait indefinitely until silence is detected on the line. This is particularly useful for reverse-911-type + call broadcast applications where you need to wait for an answering machine to complete its spiel before + playing a message.</para> + <para>Typically you will want to include two or more calls to WaitForSilence when dealing with an answering + machine; first waiting for the spiel to finish, then waiting for the beep, etc.</para> + <para>Examples:</para> + <para>WaitForSilence(500,2) will wait for 1/2 second of silence, twice</para> + <para>WaitForSilence(1000) will wait for 1 second of silence, once</para> + <para>WaitForSilence(300,3,10) will wait for 300ms silence, 3 times, and returns after 10 sec, even if silence + is not detected</para> + <para>Sets the channel variable <variable>WAITSTATUS</variable> to one of these values:</para> + <variablelist> + <variable name="WAITSTATUS"> + <value name="SILENCE"> + if exited with silence detected. + </value> + <value name="TIMEOUT"> + if exited without silence detected after timeout. + </value> + </variable> + </variablelist> + </description> + <see-also> + <ref type="application">WaitForNoise</ref> + </see-also> + </application> + <application name="WaitForNoise" language="en_US"> + <synopsis> + Waits for a specified amount of noise. + </synopsis> + <syntax> + <parameter name="noiserequired" required="true" /> + <parameter name="iterations"> + <para>If not specified, defaults to <literal>1</literal>.</para> + </parameter> + <parameter name="timeout"> + <para>Is specified only to avoid an infinite loop in cases where silence is never achieved.</para> + </parameter> + </syntax> + <description> + <para>Waits for up to <replaceable>noiserequired</replaceable> milliseconds of noise, + <replaceable>iterations</replaceable> times. An optional <replaceable>timeout</replaceable> + specified the number of seconds to return after, even if we do not receive the specified amount of noise. + Use <replaceable>timeout</replaceable> with caution, as it may defeat the purpose of this application, which + is to wait indefinitely until noise is detected on the line.</para> + </description> + <see-also> + <ref type="application">WaitForSilence</ref> + </see-also> + </application> + ***/ +static char *app_silence = "WaitForSilence"; static char *app_noise = "WaitForNoise"; -static char *synopsis_noise = "Waits for a specified amount of noise"; -static char *descrip_noise = -"WaitForNoise(noiserequired[,iterations][,timeout]) \n" -"Wait for Noise: The same as Wait for Silance but waits for noise that is above the threshold specified\n"; static int do_waiting(struct ast_channel *chan, int timereqd, time_t waitstart, int timeout, int wait_for_silence) { struct ast_frame *f = NULL; @@ -211,8 +253,8 @@ static int load_module(void) { int res; - res = ast_register_application(app_silence, waitforsilence_exec, synopsis_silence, descrip_silence); - res |= ast_register_application(app_noise, waitfornoise_exec, synopsis_noise, descrip_noise); + res = ast_register_application_xml(app_silence, waitforsilence_exec); + res |= ast_register_application_xml(app_noise, waitfornoise_exec); return res; } |