Add XML documentation for:
authorEliel C. Sardanons <eliels@gmail.com>
Mon, 3 Nov 2008 01:01:25 +0000 (01:01 +0000)
committerEliel C. Sardanons <eliels@gmail.com>
Mon, 3 Nov 2008 01:01:25 +0000 (01:01 +0000)
   - 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

apps/app_db.c
apps/app_ivrdemo.c
apps/app_waitforring.c
apps/app_waitforsilence.c

index f141209..72b6046 100644 (file)
@@ -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;
 }
index 6dbbe71..13f4bcc 100644 (file)
@@ -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");
index f2d21e5..fd5913e 100644 (file)
@@ -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");
index eedbf15..1aa7775 100644 (file)
@@ -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;
 }