From 24a04054ad848eca88b60d4bddb87805eb8c7e76 Mon Sep 17 00:00:00 2001 From: Naveen Albert Date: Thu, 25 Nov 2021 18:41:18 +0000 Subject: [PATCH] documentation: Standardize examples Most examples in the XML documentation use the example tag to demonstrate examples, which gets parsed specially in the Wiki to make it easier to follow for users. This fixes a few modules to use the example tag instead of vanilla para tags to bring them in line with the standard syntax. ASTERISK-29777 #close Change-Id: I9acb6cc5faf1d220e73c6dd28592371d768d279b --- apps/app_dtmfstore.c | 16 +++++++++++----- apps/app_mp3.c | 6 ++++-- apps/app_queue.c | 22 ++++++++++++++++------ apps/app_waitforsilence.c | 17 +++++++++-------- channels/chan_sip.c | 24 +++++++++++++----------- funcs/func_devstate.c | 6 ++++-- res/res_agi.c | 26 +++++++++++--------------- res/res_xmpp.c | 14 ++++++++++---- 8 files changed, 78 insertions(+), 53 deletions(-) diff --git a/apps/app_dtmfstore.c b/apps/app_dtmfstore.c index 4e97334e10..641170f193 100644 --- a/apps/app_dtmfstore.c +++ b/apps/app_dtmfstore.c @@ -46,7 +46,8 @@ - Must be TX or RX. + Must be TX or RX to + store digits, or remove to disable. @@ -58,10 +59,15 @@ max_digits: The maximum number of digits to store in the variable. Defaults to 0 (no maximum). After reading maximum digits, no more digits will be stored. - For example: - StoreDTMF(TX,CDR(digits)) - StoreDTMF(RX,testvar,24) - StoreDTMF(remove) + + same => n,StoreDTMF(TX,CDR(digits)) + + + same => n,StoreDTMF(RX,testvar,24) + + + same => n,StoreDTMF(remove) + ***/ diff --git a/apps/app_mp3.c b/apps/app_mp3.c index 842224025a..888f21a820 100644 --- a/apps/app_mp3.c +++ b/apps/app_mp3.c @@ -65,9 +65,11 @@ Executes mpg123 to play the given location, which typically would be a mp3 filename or m3u playlist filename or a URL. Please read http://en.wikipedia.org/wiki/M3U - to see how M3U playlist file format is like, Example usage would be + to see what the M3U playlist file format is like. + User can exit by pressing any key on the dialpad, or by hanging up. + exten => 1234,1,MP3Player(/var/lib/asterisk/playlist.m3u) - User can exit by pressing any key on the dialpad, or by hanging up. + This application does not automatically answer and should be preceeded by an application such as Answer() or Progress(). diff --git a/apps/app_queue.c b/apps/app_queue.c index 4f5913afd7..b5cd1636be 100644 --- a/apps/app_queue.c +++ b/apps/app_queue.c @@ -376,7 +376,9 @@ - Example: RemoveQueueMember(techsupport,SIP/3000) + + same => n,RemoveQueueMember(techsupport,SIP/3000) + Queue @@ -421,7 +423,9 @@ - Example: PauseQueueMember(,SIP/3000) + + same => n,PauseQueueMember(,SIP/3000) + Queue @@ -463,7 +467,9 @@ - Example: UnpauseQueueMember(,SIP/3000) + + same => n,UnpauseQueueMember(,SIP/3000) + Queue @@ -495,7 +501,9 @@ Allows you to write your own events into the queue log. - Example: QueueLog(101,${UNIQUEID},${AGENT},WENTONBREAK,600) + + same => n,QueueLog(101,${UNIQUEID},${AGENT},WENTONBREAK,600) + Queue @@ -516,7 +524,7 @@ - Writes to the queue_log file for OutBound calls and updates Realtime Data. + Writes to the queue_log file for outbound calls and updates Realtime Data. Is used at h extension to be able to have all the parameters. @@ -529,7 +537,9 @@ Allows you to write Outbound events into the queue log. - Example: exten => h,1,QueueUpdate(${QUEUE}, ${UNIQUEID}, ${AGENT}, ${DIALSTATUS}, ${ANSWEREDTIME}, ${DIALEDTIME} | ${DIALEDNUMBER}) + + exten => h,1,QueueUpdate(${QUEUE}, ${UNIQUEID}, ${AGENT}, ${DIALSTATUS}, ${ANSWEREDTIME}, ${DIALEDTIME} | ${DIALEDNUMBER}) + diff --git a/apps/app_waitforsilence.c b/apps/app_waitforsilence.c index 52248ac097..9820de253f 100644 --- a/apps/app_waitforsilence.c +++ b/apps/app_waitforsilence.c @@ -23,9 +23,6 @@ * * \brief Wait for Silence * - Waits for up to 'x' milliseconds of silence, 'y' times \n - * - WaitForSilence(500,2) will wait for 1/2 second of silence, twice \n - * - WaitForSilence(1000,1) will wait for 1 second of silence, once \n - * - WaitForSilence(300,3,10) will wait for 300ms of silence, 3 times, and return after 10sec \n * * \author David C. Troy * @@ -78,11 +75,15 @@ playing a message. 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. - Examples: - WaitForSilence(500,2) will wait for 1/2 second of silence, twice - WaitForSilence(1000) will wait for 1 second of silence, once - WaitForSilence(300,3,10) will wait for 300ms silence, 3 times, and returns after 10 sec, even if silence - is not detected + + same => n,WaitForSilence(500,2) + + + same => n,WaitForSilence(1000) + + + same => n,WaitForSilence(300,3,10) + Sets the channel variable WAITSTATUS to one of these values: diff --git a/channels/chan_sip.c b/channels/chan_sip.c index 99d461ff54..3e310e133e 100644 --- a/channels/chan_sip.c +++ b/channels/chan_sip.c @@ -339,17 +339,19 @@ added with SIPAddHeader(). If no parameter is supplied, all previously added headers will be removed. If a parameter is supplied, only the matching headers will be removed. - For example you have added these 2 headers: - SIPAddHeader(P-Asserted-Identity: sip:foo@bar); - SIPAddHeader(P-Preferred-Identity: sip:bar@foo); - - // remove all headers - SIPRemoveHeader(); - // remove all P- headers - SIPRemoveHeader(P-); - // remove only the PAI header (note the : at the end) - SIPRemoveHeader(P-Asserted-Identity:); - + + same => n,SIPAddHeader(P-Asserted-Identity: sip:foo@bar) + same => n,SIPAddHeader(P-Preferred-Identity: sip:bar@foo) + + + same => n,SIPRemoveHeader() + + + same => n,SIPRemoveHeader(P-) + + + same => n,SIPRemoveHeader(P-Asserted-Identity:) + Always returns 0. diff --git a/funcs/func_devstate.c b/funcs/func_devstate.c index e6159e9bdb..d09f9d8f3a 100644 --- a/funcs/func_devstate.c +++ b/funcs/func_devstate.c @@ -90,8 +90,10 @@ The HINT function can be used to retrieve the list of devices that are - mapped to a dialplan hint. For example: - NoOp(Hint for Extension 1234 is ${HINT(1234)}) + mapped to a dialplan hint. + + same => n,NoOp(Hint for Extension 1234 is ${HINT(1234)}) + ***/ diff --git a/res/res_agi.c b/res/res_agi.c index 631c9b844c..8bdb7ed385 100644 --- a/res/res_agi.c +++ b/res/res_agi.c @@ -1185,21 +1185,17 @@ after a channel hangup is detected, set the AGIEXITONHANGUP variable to yes. - - ; Start the AGI script /tmp/my-cool-script.sh, passing it the contents - ; of the channel variable FOO - same => n,AGI(/tmp/my-cool-script.sh,${FOO}) - - ; Start the AGI script my-cool-script.sh located in the astagidir - ; directory, specified in asterisk.conf - same => n,AGI(my-cool-script.sh) - - ; Connect to the FastAGI server located at 127.0.0.1 and start the script - ; awesome-script - same => n,AGI(agi://127.0.0.1/awesome-script) - - ; Start AsyncAGI - same => n,AGI(agi:async) + + same => n,AGI(/tmp/my-cool-script.sh,${FOO}) + + + same => n,AGI(my-cool-script.sh) + + + same => n,AGI(agi://127.0.0.1/awesome-script) + + + same => n,AGI(agi:async) This application sets the following channel variable upon completion: diff --git a/res/res_xmpp.c b/res/res_xmpp.c index 8db0da8ea5..2f1e0eb035 100644 --- a/res/res_xmpp.c +++ b/res/res_xmpp.c @@ -84,9 +84,12 @@ Sends the content of message as text message from the given account to the buddy identified by jid - Example: JabberSend(asterisk,bob@domain.com,Hello world) sends "Hello world" - to bob@domain.com as an XMPP message from the account + The example below sends "Hello world" to + bob@domain.com as an XMPP message from the account asterisk, configured in xmpp.conf. + + same => n,JabberSend(asterisk,bob@domain.com,Hello world) + JABBER_STATUS @@ -113,9 +116,12 @@ Receives a text message on the given account from the buddy identified by jid and returns the contents. - Example: ${JABBER_RECEIVE(asterisk,bob@domain.com)} returns an XMPP message - sent from bob@domain.com (or nothing in case of a time out), to + The example below returns an XMPP message sent from + bob@domain.com (or nothing in case of a time out), to the asterisk XMPP account configured in xmpp.conf. + + same => n,Set(msg=${JABBER_RECEIVE(asterisk,bob@domain.com)}) + JABBER_STATUS