<p>Kevin Harwell <strong>submitted</strong> this change.</p><p><a href="https://gerrit.asterisk.org/c/asterisk/+/17607">View Change</a></p><div style="white-space:pre-wrap">Approvals:
Kevin Harwell: Looks good to me, approved; Approved for Submit
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">documentation: Standardize examples<br><br>Most examples in the XML documentation use the<br>example tag to demonstrate examples, which gets<br>parsed specially in the Wiki to make it easier<br>to follow for users.<br><br>This fixes a few modules to use the example<br>tag instead of vanilla para tags to bring them<br>in line with the standard syntax.<br><br>ASTERISK-29777 #close<br><br>Change-Id: I9acb6cc5faf1d220e73c6dd28592371d768d279b<br>---<br>M apps/app_dtmfstore.c<br>M apps/app_mp3.c<br>M apps/app_queue.c<br>M apps/app_waitforsilence.c<br>M channels/chan_sip.c<br>M funcs/func_devstate.c<br>M res/res_agi.c<br>M res/res_xmpp.c<br>8 files changed, 78 insertions(+), 53 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/apps/app_dtmfstore.c b/apps/app_dtmfstore.c</span><br><span>index 4e97334..641170f 100644</span><br><span>--- a/apps/app_dtmfstore.c</span><br><span>+++ b/apps/app_dtmfstore.c</span><br><span>@@ -46,7 +46,8 @@</span><br><span> </synopsis></span><br><span> <syntax></span><br><span> <parameter name="direction" required="true"></span><br><span style="color: hsl(0, 100%, 40%);">- <para>Must be <literal>TX</literal> or <literal>RX</literal>.</para></span><br><span style="color: hsl(120, 100%, 40%);">+ <para>Must be <literal>TX</literal> or <literal>RX</literal> to</span><br><span style="color: hsl(120, 100%, 40%);">+ store digits, or <literal>remove</literal> to disable.</para></span><br><span> </parameter></span><br><span> </syntax></span><br><span> <description></span><br><span>@@ -58,10 +59,15 @@</span><br><span> <para><replaceable>max_digits</replaceable>: The maximum number of digits to</span><br><span> store in the variable. Defaults to 0 (no maximum). After reading <literal></span><br><span> maximum</literal> digits, no more digits will be stored.</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>For example:</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>StoreDTMF(TX,CDR(digits))</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>StoreDTMF(RX,testvar,24)</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>StoreDTMF(remove)</para></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Store digits in CDR variable"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,StoreDTMF(TX,CDR(digits))</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Store up to 24 digits"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,StoreDTMF(RX,testvar,24)</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Disable digit collection"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,StoreDTMF(remove)</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span> </description></span><br><span> </application></span><br><span> ***/</span><br><span>diff --git a/apps/app_mp3.c b/apps/app_mp3.c</span><br><span>index 8422240..888f21a 100644</span><br><span>--- a/apps/app_mp3.c</span><br><span>+++ b/apps/app_mp3.c</span><br><span>@@ -65,9 +65,11 @@</span><br><span> <description></span><br><span> <para>Executes mpg123 to play the given location, which typically would be a mp3 filename</span><br><span> or m3u playlist filename or a URL. Please read http://en.wikipedia.org/wiki/M3U</span><br><span style="color: hsl(0, 100%, 40%);">- to see how M3U playlist file format is like, Example usage would be</span><br><span style="color: hsl(120, 100%, 40%);">+ to see what the M3U playlist file format is like.</para></span><br><span style="color: hsl(120, 100%, 40%);">+ <para>User can exit by pressing any key on the dialpad, or by hanging up.</para></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Play an MP3 playlist"></span><br><span> exten => 1234,1,MP3Player(/var/lib/asterisk/playlist.m3u)</span><br><span style="color: hsl(0, 100%, 40%);">- User can exit by pressing any key on the dialpad, or by hanging up.</para></span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span> <para>This application does not automatically answer and should be preceeded by an</span><br><span> application such as Answer() or Progress().</para></span><br><span> </description></span><br><span>diff --git a/apps/app_queue.c b/apps/app_queue.c</span><br><span>index f4b9004..86a2682 100644</span><br><span>--- a/apps/app_queue.c</span><br><span>+++ b/apps/app_queue.c</span><br><span>@@ -376,7 +376,9 @@</span><br><span> <value name="NOTDYNAMIC" /></span><br><span> </variable></span><br><span> </variablelist></span><br><span style="color: hsl(0, 100%, 40%);">- <para>Example: RemoveQueueMember(techsupport,SIP/3000)</para></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Remove queue member"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,RemoveQueueMember(techsupport,SIP/3000)</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span> </description></span><br><span> <see-also></span><br><span> <ref type="application">Queue</ref></span><br><span>@@ -421,7 +423,9 @@</span><br><span> <value name="NOTFOUND" /></span><br><span> </variable></span><br><span> </variablelist></span><br><span style="color: hsl(0, 100%, 40%);">- <para>Example: PauseQueueMember(,SIP/3000)</para></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Pause queue member"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,PauseQueueMember(,SIP/3000)</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span> </description></span><br><span> <see-also></span><br><span> <ref type="application">Queue</ref></span><br><span>@@ -463,7 +467,9 @@</span><br><span> <value name="NOTFOUND" /></span><br><span> </variable></span><br><span> </variablelist></span><br><span style="color: hsl(0, 100%, 40%);">- <para>Example: UnpauseQueueMember(,SIP/3000)</para></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Unpause queue member"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,UnpauseQueueMember(,SIP/3000)</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span> </description></span><br><span> <see-also></span><br><span> <ref type="application">Queue</ref></span><br><span>@@ -495,7 +501,9 @@</span><br><span> </syntax></span><br><span> <description></span><br><span> <para>Allows you to write your own events into the queue log.</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>Example: QueueLog(101,${UNIQUEID},${AGENT},WENTONBREAK,600)</para></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Log custom queue event"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,QueueLog(101,${UNIQUEID},${AGENT},WENTONBREAK,600)</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span> </description></span><br><span> <see-also></span><br><span> <ref type="application">Queue</ref></span><br><span>@@ -516,7 +524,7 @@</span><br><span> </application></span><br><span> <application name="QueueUpdate" language="en_US"></span><br><span> <synopsis></span><br><span style="color: hsl(0, 100%, 40%);">- Writes to the queue_log file for OutBound calls and updates Realtime Data.</span><br><span style="color: hsl(120, 100%, 40%);">+ Writes to the queue_log file for outbound calls and updates Realtime Data.</span><br><span> Is used at h extension to be able to have all the parameters.</span><br><span> </synopsis></span><br><span> <syntax></span><br><span>@@ -529,7 +537,9 @@</span><br><span> </syntax></span><br><span> <description></span><br><span> <para>Allows you to write Outbound events into the queue log.</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>Example: exten => h,1,QueueUpdate(${QUEUE}, ${UNIQUEID}, ${AGENT}, ${DIALSTATUS}, ${ANSWEREDTIME}, ${DIALEDTIME} | ${DIALEDNUMBER})</para></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Write outbound event into queue log"></span><br><span style="color: hsl(120, 100%, 40%);">+ exten => h,1,QueueUpdate(${QUEUE}, ${UNIQUEID}, ${AGENT}, ${DIALSTATUS}, ${ANSWEREDTIME}, ${DIALEDTIME} | ${DIALEDNUMBER})</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span> </description></span><br><span> </application></span><br><span> <function name="QUEUE_VARIABLES" language="en_US"></span><br><span>diff --git a/apps/app_waitforsilence.c b/apps/app_waitforsilence.c</span><br><span>index 52248ac..9820de2 100644</span><br><span>--- a/apps/app_waitforsilence.c</span><br><span>+++ b/apps/app_waitforsilence.c</span><br><span>@@ -23,9 +23,6 @@</span><br><span> *</span><br><span> * \brief Wait for Silence</span><br><span> * - Waits for up to 'x' milliseconds of silence, 'y' times \n</span><br><span style="color: hsl(0, 100%, 40%);">- * - WaitForSilence(500,2) will wait for 1/2 second of silence, twice \n</span><br><span style="color: hsl(0, 100%, 40%);">- * - WaitForSilence(1000,1) will wait for 1 second of silence, once \n</span><br><span style="color: hsl(0, 100%, 40%);">- * - WaitForSilence(300,3,10) will wait for 300ms of silence, 3 times, and return after 10sec \n</span><br><span> *</span><br><span> * \author David C. Troy <dave@popvox.com></span><br><span> *</span><br><span>@@ -78,11 +75,15 @@</span><br><span> playing a message.</para></span><br><span> <para>Typically you will want to include two or more calls to WaitForSilence when dealing with an answering</span><br><span> machine; first waiting for the spiel to finish, then waiting for the beep, etc.</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>Examples:</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>WaitForSilence(500,2) will wait for 1/2 second of silence, twice</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>WaitForSilence(1000) will wait for 1 second of silence, once</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>WaitForSilence(300,3,10) will wait for 300ms silence, 3 times, and returns after 10 sec, even if silence</span><br><span style="color: hsl(0, 100%, 40%);">- is not detected</para></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Wait for half a second of silence, twice"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,WaitForSilence(500,2)</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Wait for one second of silence, once"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,WaitForSilence(1000)</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Wait for 300 ms of silence, 3 times, and returns after 10 seconds, even if no silence detected"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,WaitForSilence(300,3,10)</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span> <para>Sets the channel variable <variable>WAITSTATUS</variable> to one of these values:</para></span><br><span> <variablelist></span><br><span> <variable name="WAITSTATUS"></span><br><span>diff --git a/channels/chan_sip.c b/channels/chan_sip.c</span><br><span>index 0e7a932..13d5b1f 100644</span><br><span>--- a/channels/chan_sip.c</span><br><span>+++ b/channels/chan_sip.c</span><br><span>@@ -337,17 +337,19 @@</span><br><span> added with SIPAddHeader(). If no parameter is supplied, all previously added</span><br><span> headers will be removed. If a parameter is supplied, only the matching headers</span><br><span> will be removed.</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>For example you have added these 2 headers:</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>SIPAddHeader(P-Asserted-Identity: sip:foo@bar);</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>SIPAddHeader(P-Preferred-Identity: sip:bar@foo);</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para></para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>// remove all headers</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>SIPRemoveHeader();</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>// remove all P- headers</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>SIPRemoveHeader(P-);</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>// remove only the PAI header (note the : at the end)</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>SIPRemoveHeader(P-Asserted-Identity:);</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para></para></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Add 2 headers"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,SIPAddHeader(P-Asserted-Identity: sip:foo@bar)</span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,SIPAddHeader(P-Preferred-Identity: sip:bar@foo)</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Remove all headers"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,SIPRemoveHeader()</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Remove all P- headers"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,SIPRemoveHeader(P-)</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Remove only the PAI header (note the : at the end)"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,SIPRemoveHeader(P-Asserted-Identity:)</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span> <para>Always returns <literal>0</literal>.</para></span><br><span> </description></span><br><span> </application></span><br><span>diff --git a/funcs/func_devstate.c b/funcs/func_devstate.c</span><br><span>index e6159e9..d09f9d8 100644</span><br><span>--- a/funcs/func_devstate.c</span><br><span>+++ b/funcs/func_devstate.c</span><br><span>@@ -90,8 +90,10 @@</span><br><span> </syntax></span><br><span> <description></span><br><span> <para>The HINT function can be used to retrieve the list of devices that are</span><br><span style="color: hsl(0, 100%, 40%);">- mapped to a dialplan hint. For example:</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>NoOp(Hint for Extension 1234 is ${HINT(1234)})</para></span><br><span style="color: hsl(120, 100%, 40%);">+ mapped to a dialplan hint.</para></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Hint for extension 1234"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,NoOp(Hint for Extension 1234 is ${HINT(1234)})</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span> </description></span><br><span> </function></span><br><span> ***/</span><br><span>diff --git a/res/res_agi.c b/res/res_agi.c</span><br><span>index e09bf19..56fef9b 100644</span><br><span>--- a/res/res_agi.c</span><br><span>+++ b/res/res_agi.c</span><br><span>@@ -1185,21 +1185,17 @@</span><br><span> after a channel hangup is detected, set the <variable>AGIEXITONHANGUP</variable></span><br><span> variable to <literal>yes</literal>.</para></span><br><span> </note></span><br><span style="color: hsl(0, 100%, 40%);">- <example title="AGI invocation examples"></span><br><span style="color: hsl(0, 100%, 40%);">- ; Start the AGI script /tmp/my-cool-script.sh, passing it the contents</span><br><span style="color: hsl(0, 100%, 40%);">- ; of the channel variable FOO</span><br><span style="color: hsl(0, 100%, 40%);">- same => n,AGI(/tmp/my-cool-script.sh,${FOO})</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- ; Start the AGI script my-cool-script.sh located in the astagidir</span><br><span style="color: hsl(0, 100%, 40%);">- ; directory, specified in asterisk.conf</span><br><span style="color: hsl(0, 100%, 40%);">- same => n,AGI(my-cool-script.sh)</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- ; Connect to the FastAGI server located at 127.0.0.1 and start the script</span><br><span style="color: hsl(0, 100%, 40%);">- ; awesome-script</span><br><span style="color: hsl(0, 100%, 40%);">- same => n,AGI(agi://127.0.0.1/awesome-script)</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- ; Start AsyncAGI</span><br><span style="color: hsl(0, 100%, 40%);">- same => n,AGI(agi:async)</span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Start the AGI script /tmp/my-cool-script.sh, passing it the contents of the channel variable FOO"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,AGI(/tmp/my-cool-script.sh,${FOO})</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Start the AGI script my-cool-script.sh located in the astagidir directory, specified in asterisk.conf"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,AGI(my-cool-script.sh)</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Connect to the FastAGI server located at 127.0.0.1 and start the script awesome-script"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,AGI(agi://127.0.0.1/awesome-script)</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Start AsyncAGI"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,AGI(agi:async)</span><br><span> </example></span><br><span> <para>This application sets the following channel variable upon completion:</para></span><br><span> <variablelist></span><br><span>diff --git a/res/res_xmpp.c b/res/res_xmpp.c</span><br><span>index 69a7770..28b2d08 100644</span><br><span>--- a/res/res_xmpp.c</span><br><span>+++ b/res/res_xmpp.c</span><br><span>@@ -84,9 +84,12 @@</span><br><span> <para>Sends the content of <replaceable>message</replaceable> as text message</span><br><span> from the given <replaceable>account</replaceable> to the buddy identified by</span><br><span> <replaceable>jid</replaceable></para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>Example: JabberSend(asterisk,bob@domain.com,Hello world) sends "Hello world"</span><br><span style="color: hsl(0, 100%, 40%);">- to <replaceable>bob@domain.com</replaceable> as an XMPP message from the account</span><br><span style="color: hsl(120, 100%, 40%);">+ <para>The example below sends "Hello world" to</span><br><span style="color: hsl(120, 100%, 40%);">+ <replaceable>bob@domain.com</replaceable> as an XMPP message from the account</span><br><span> <replaceable>asterisk</replaceable>, configured in xmpp.conf.</para></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Send 'Hello world' to Bob"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,JabberSend(asterisk,bob@domain.com,Hello world)</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span> </description></span><br><span> <see-also></span><br><span> <ref type="function" module="res_xmpp">JABBER_STATUS</ref></span><br><span>@@ -113,9 +116,12 @@</span><br><span> <description></span><br><span> <para>Receives a text message on the given <replaceable>account</replaceable></span><br><span> from the buddy identified by <replaceable>jid</replaceable> and returns the contents.</para></span><br><span style="color: hsl(0, 100%, 40%);">- <para>Example: ${JABBER_RECEIVE(asterisk,bob@domain.com)} returns an XMPP message</span><br><span style="color: hsl(0, 100%, 40%);">- sent from <replaceable>bob@domain.com</replaceable> (or nothing in case of a time out), to</span><br><span style="color: hsl(120, 100%, 40%);">+ <para>The example below returns an XMPP message sent from</span><br><span style="color: hsl(120, 100%, 40%);">+ <replaceable>bob@domain.com</replaceable> (or nothing in case of a time out), to</span><br><span> the <replaceable>asterisk</replaceable> XMPP account configured in xmpp.conf.</para></span><br><span style="color: hsl(120, 100%, 40%);">+ <example title="Receive a message"></span><br><span style="color: hsl(120, 100%, 40%);">+ same => n,Set(msg=${JABBER_RECEIVE(asterisk,bob@domain.com)})</span><br><span style="color: hsl(120, 100%, 40%);">+ </example></span><br><span> </description></span><br><span> <see-also></span><br><span> <ref type="function" module="res_xmpp">JABBER_STATUS</ref></span><br><span></span><br></pre><div style="white-space:pre-wrap"></div><p>To view, visit <a href="https://gerrit.asterisk.org/c/asterisk/+/17607">change 17607</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.asterisk.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.asterisk.org/c/asterisk/+/17607"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: asterisk </div>
<div style="display:none"> Gerrit-Branch: 16 </div>
<div style="display:none"> Gerrit-Change-Id: I9acb6cc5faf1d220e73c6dd28592371d768d279b </div>
<div style="display:none"> Gerrit-Change-Number: 17607 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: N A <mail@interlinked.x10host.com> </div>
<div style="display:none"> Gerrit-Reviewer: Friendly Automation </div>
<div style="display:none"> Gerrit-Reviewer: Kevin Harwell <kharwell@digium.com> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>