Skip to content

Commit 24a0405

Browse files
InterLinked1Friendly Automation
InterLinked1
authored and
Friendly Automation
committed
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
1 parent 2478bfc commit 24a0405

8 files changed

Lines changed: 78 additions & 53 deletions

File tree

‎apps/app_dtmfstore.c‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,8 @@
4646
</synopsis>
4747
<syntax>
4848
<parameter name="direction" required="true">
49-
<para>Must be <literal>TX</literal> or <literal>RX</literal>.</para>
49+
<para>Must be <literal>TX</literal> or <literal>RX</literal> to
50+
store digits, or <literal>remove</literal> to disable.</para>
5051
</parameter>
5152
</syntax>
5253
<description>
@@ -58,10 +59,15 @@
5859
<para><replaceable>max_digits</replaceable>: The maximum number of digits to
5960
store in the variable. Defaults to 0 (no maximum). After reading <literal>
6061
maximum</literal> digits, no more digits will be stored.</para>
61-
<para>For example:</para>
62-
<para>StoreDTMF(TX,CDR(digits))</para>
63-
<para>StoreDTMF(RX,testvar,24)</para>
64-
<para>StoreDTMF(remove)</para>
62+
<example title="Store digits in CDR variable">
63+
same => n,StoreDTMF(TX,CDR(digits))
64+
</example>
65+
<example title="Store up to 24 digits">
66+
same => n,StoreDTMF(RX,testvar,24)
67+
</example>
68+
<example title="Disable digit collection">
69+
same => n,StoreDTMF(remove)
70+
</example>
6571
</description>
6672
</application>
6773
***/

‎apps/app_mp3.c‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,9 +65,11 @@
6565
<description>
6666
<para>Executes mpg123 to play the given location, which typically would be a mp3 filename
6767
or m3u playlist filename or a URL. Please read http://en.wikipedia.org/wiki/M3U
68-
to see how M3U playlist file format is like, Example usage would be
68+
to see what the M3U playlist file format is like.</para>
69+
<para>User can exit by pressing any key on the dialpad, or by hanging up.</para>
70+
<example title="Play an MP3 playlist">
6971
exten => 1234,1,MP3Player(/var/lib/asterisk/playlist.m3u)
70-
User can exit by pressing any key on the dialpad, or by hanging up.</para>
72+
</example>
7173
<para>This application does not automatically answer and should be preceeded by an
7274
application such as Answer() or Progress().</para>
7375
</description>

‎apps/app_queue.c‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -376,7 +376,9 @@
376376
<value name="NOTDYNAMIC" />
377377
</variable>
378378
</variablelist>
379-
<para>Example: RemoveQueueMember(techsupport,SIP/3000)</para>
379+
<example title="Remove queue member">
380+
same => n,RemoveQueueMember(techsupport,SIP/3000)
381+
</example>
380382
</description>
381383
<see-also>
382384
<ref type="application">Queue</ref>
@@ -421,7 +423,9 @@
421423
<value name="NOTFOUND" />
422424
</variable>
423425
</variablelist>
424-
<para>Example: PauseQueueMember(,SIP/3000)</para>
426+
<example title="Pause queue member">
427+
same => n,PauseQueueMember(,SIP/3000)
428+
</example>
425429
</description>
426430
<see-also>
427431
<ref type="application">Queue</ref>
@@ -463,7 +467,9 @@
463467
<value name="NOTFOUND" />
464468
</variable>
465469
</variablelist>
466-
<para>Example: UnpauseQueueMember(,SIP/3000)</para>
470+
<example title="Unpause queue member">
471+
same => n,UnpauseQueueMember(,SIP/3000)
472+
</example>
467473
</description>
468474
<see-also>
469475
<ref type="application">Queue</ref>
@@ -495,7 +501,9 @@
495501
</syntax>
496502
<description>
497503
<para>Allows you to write your own events into the queue log.</para>
498-
<para>Example: QueueLog(101,${UNIQUEID},${AGENT},WENTONBREAK,600)</para>
504+
<example title="Log custom queue event">
505+
same => n,QueueLog(101,${UNIQUEID},${AGENT},WENTONBREAK,600)
506+
</example>
499507
</description>
500508
<see-also>
501509
<ref type="application">Queue</ref>
@@ -516,7 +524,7 @@
516524
</application>
517525
<application name="QueueUpdate" language="en_US">
518526
<synopsis>
519-
Writes to the queue_log file for OutBound calls and updates Realtime Data.
527+
Writes to the queue_log file for outbound calls and updates Realtime Data.
520528
Is used at h extension to be able to have all the parameters.
521529
</synopsis>
522530
<syntax>
@@ -529,7 +537,9 @@
529537
</syntax>
530538
<description>
531539
<para>Allows you to write Outbound events into the queue log.</para>
532-
<para>Example: exten => h,1,QueueUpdate(${QUEUE}, ${UNIQUEID}, ${AGENT}, ${DIALSTATUS}, ${ANSWEREDTIME}, ${DIALEDTIME} | ${DIALEDNUMBER})</para>
540+
<example title="Write outbound event into queue log">
541+
exten => h,1,QueueUpdate(${QUEUE}, ${UNIQUEID}, ${AGENT}, ${DIALSTATUS}, ${ANSWEREDTIME}, ${DIALEDTIME} | ${DIALEDNUMBER})
542+
</example>
533543
</description>
534544
</application>
535545
<function name="QUEUE_VARIABLES" language="en_US">

‎apps/app_waitforsilence.c‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,6 @@
2323
*
2424
* \brief Wait for Silence
2525
* - Waits for up to 'x' milliseconds of silence, 'y' times \n
26-
* - WaitForSilence(500,2) will wait for 1/2 second of silence, twice \n
27-
* - WaitForSilence(1000,1) will wait for 1 second of silence, once \n
28-
* - WaitForSilence(300,3,10) will wait for 300ms of silence, 3 times, and return after 10sec \n
2926
*
3027
* \author David C. Troy <dave@popvox.com>
3128
*
@@ -78,11 +75,15 @@
7875
playing a message.</para>
7976
<para>Typically you will want to include two or more calls to WaitForSilence when dealing with an answering
8077
machine; first waiting for the spiel to finish, then waiting for the beep, etc.</para>
81-
<para>Examples:</para>
82-
<para>WaitForSilence(500,2) will wait for 1/2 second of silence, twice</para>
83-
<para>WaitForSilence(1000) will wait for 1 second of silence, once</para>
84-
<para>WaitForSilence(300,3,10) will wait for 300ms silence, 3 times, and returns after 10 sec, even if silence
85-
is not detected</para>
78+
<example title="Wait for half a second of silence, twice">
79+
same => n,WaitForSilence(500,2)
80+
</example>
81+
<example title="Wait for one second of silence, once">
82+
same => n,WaitForSilence(1000)
83+
</example>
84+
<example title="Wait for 300 ms of silence, 3 times, and returns after 10 seconds, even if no silence detected">
85+
same => n,WaitForSilence(300,3,10)
86+
</example>
8687
<para>Sets the channel variable <variable>WAITSTATUS</variable> to one of these values:</para>
8788
<variablelist>
8889
<variable name="WAITSTATUS">

‎channels/chan_sip.c‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -339,17 +339,19 @@
339339
added with SIPAddHeader(). If no parameter is supplied, all previously added
340340
headers will be removed. If a parameter is supplied, only the matching headers
341341
will be removed.</para>
342-
<para>For example you have added these 2 headers:</para>
343-
<para>SIPAddHeader(P-Asserted-Identity: sip:foo@bar);</para>
344-
<para>SIPAddHeader(P-Preferred-Identity: sip:bar@foo);</para>
345-
<para></para>
346-
<para>// remove all headers</para>
347-
<para>SIPRemoveHeader();</para>
348-
<para>// remove all P- headers</para>
349-
<para>SIPRemoveHeader(P-);</para>
350-
<para>// remove only the PAI header (note the : at the end)</para>
351-
<para>SIPRemoveHeader(P-Asserted-Identity:);</para>
352-
<para></para>
342+
<example title="Add 2 headers">
343+
same => n,SIPAddHeader(P-Asserted-Identity: sip:foo@bar)
344+
same => n,SIPAddHeader(P-Preferred-Identity: sip:bar@foo)
345+
</example>
346+
<example title="Remove all headers">
347+
same => n,SIPRemoveHeader()
348+
</example>
349+
<example title="Remove all P- headers">
350+
same => n,SIPRemoveHeader(P-)
351+
</example>
352+
<example title="Remove only the PAI header (note the : at the end)">
353+
same => n,SIPRemoveHeader(P-Asserted-Identity:)
354+
</example>
353355
<para>Always returns <literal>0</literal>.</para>
354356
</description>
355357
</application>

‎funcs/func_devstate.c‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -90,8 +90,10 @@
9090
</syntax>
9191
<description>
9292
<para>The HINT function can be used to retrieve the list of devices that are
93-
mapped to a dialplan hint. For example:</para>
94-
<para>NoOp(Hint for Extension 1234 is ${HINT(1234)})</para>
93+
mapped to a dialplan hint.</para>
94+
<example title="Hint for extension 1234">
95+
same => n,NoOp(Hint for Extension 1234 is ${HINT(1234)})
96+
</example>
9597
</description>
9698
</function>
9799
***/

‎res/res_agi.c‎

Lines changed: 11 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1185,21 +1185,17 @@
11851185
after a channel hangup is detected, set the <variable>AGIEXITONHANGUP</variable>
11861186
variable to <literal>yes</literal>.</para>
11871187
</note>
1188-
<example title="AGI invocation examples">
1189-
; Start the AGI script /tmp/my-cool-script.sh, passing it the contents
1190-
; of the channel variable FOO
1191-
same => n,AGI(/tmp/my-cool-script.sh,${FOO})
1192-
1193-
; Start the AGI script my-cool-script.sh located in the astagidir
1194-
; directory, specified in asterisk.conf
1195-
same => n,AGI(my-cool-script.sh)
1196-
1197-
; Connect to the FastAGI server located at 127.0.0.1 and start the script
1198-
; awesome-script
1199-
same => n,AGI(agi://127.0.0.1/awesome-script)
1200-
1201-
; Start AsyncAGI
1202-
same => n,AGI(agi:async)
1188+
<example title="Start the AGI script /tmp/my-cool-script.sh, passing it the contents of the channel variable FOO">
1189+
same => n,AGI(/tmp/my-cool-script.sh,${FOO})
1190+
</example>
1191+
<example title="Start the AGI script my-cool-script.sh located in the astagidir directory, specified in asterisk.conf">
1192+
same => n,AGI(my-cool-script.sh)
1193+
</example>
1194+
<example title="Connect to the FastAGI server located at 127.0.0.1 and start the script awesome-script">
1195+
same => n,AGI(agi://127.0.0.1/awesome-script)
1196+
</example>
1197+
<example title="Start AsyncAGI">
1198+
same => n,AGI(agi:async)
12031199
</example>
12041200
<para>This application sets the following channel variable upon completion:</para>
12051201
<variablelist>

‎res/res_xmpp.c‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -84,9 +84,12 @@
8484
<para>Sends the content of <replaceable>message</replaceable> as text message
8585
from the given <replaceable>account</replaceable> to the buddy identified by
8686
<replaceable>jid</replaceable></para>
87-
<para>Example: JabberSend(asterisk,bob@domain.com,Hello world) sends "Hello world"
88-
to <replaceable>bob@domain.com</replaceable> as an XMPP message from the account
87+
<para>The example below sends "Hello world" to
88+
<replaceable>bob@domain.com</replaceable> as an XMPP message from the account
8989
<replaceable>asterisk</replaceable>, configured in xmpp.conf.</para>
90+
<example title="Send 'Hello world' to Bob">
91+
same => n,JabberSend(asterisk,bob@domain.com,Hello world)
92+
</example>
9093
</description>
9194
<see-also>
9295
<ref type="function" module="res_xmpp">JABBER_STATUS</ref>
@@ -113,9 +116,12 @@
113116
<description>
114117
<para>Receives a text message on the given <replaceable>account</replaceable>
115118
from the buddy identified by <replaceable>jid</replaceable> and returns the contents.</para>
116-
<para>Example: ${JABBER_RECEIVE(asterisk,bob@domain.com)} returns an XMPP message
117-
sent from <replaceable>bob@domain.com</replaceable> (or nothing in case of a time out), to
119+
<para>The example below returns an XMPP message sent from
120+
<replaceable>bob@domain.com</replaceable> (or nothing in case of a time out), to
118121
the <replaceable>asterisk</replaceable> XMPP account configured in xmpp.conf.</para>
122+
<example title="Receive a message">
123+
same => n,Set(msg=${JABBER_RECEIVE(asterisk,bob@domain.com)})
124+
</example>
119125
</description>
120126
<see-also>
121127
<ref type="function" module="res_xmpp">JABBER_STATUS</ref>

0 commit comments

Comments
 (0)