[Asterisk-code-review] documentation: Standardize examples (asterisk[18])
Kevin Harwell
asteriskteam at digium.com
Thu Dec 2 09:12:58 CST 2021
Kevin Harwell has submitted this change. ( https://gerrit.asterisk.org/c/asterisk/+/17608 )
Change subject: documentation: Standardize examples
......................................................................
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
---
M apps/app_dtmfstore.c
M apps/app_mp3.c
M apps/app_queue.c
M apps/app_waitforsilence.c
M channels/chan_sip.c
M funcs/func_devstate.c
M res/res_agi.c
M res/res_xmpp.c
8 files changed, 78 insertions(+), 53 deletions(-)
Approvals:
Kevin Harwell: Looks good to me, approved; Approved for Submit
diff --git a/apps/app_dtmfstore.c b/apps/app_dtmfstore.c
index 4e97334..641170f 100644
--- a/apps/app_dtmfstore.c
+++ b/apps/app_dtmfstore.c
@@ -46,7 +46,8 @@
</synopsis>
<syntax>
<parameter name="direction" required="true">
- <para>Must be <literal>TX</literal> or <literal>RX</literal>.</para>
+ <para>Must be <literal>TX</literal> or <literal>RX</literal> to
+ store digits, or <literal>remove</literal> to disable.</para>
</parameter>
</syntax>
<description>
@@ -58,10 +59,15 @@
<para><replaceable>max_digits</replaceable>: The maximum number of digits to
store in the variable. Defaults to 0 (no maximum). After reading <literal>
maximum</literal> digits, no more digits will be stored.</para>
- <para>For example:</para>
- <para>StoreDTMF(TX,CDR(digits))</para>
- <para>StoreDTMF(RX,testvar,24)</para>
- <para>StoreDTMF(remove)</para>
+ <example title="Store digits in CDR variable">
+ same => n,StoreDTMF(TX,CDR(digits))
+ </example>
+ <example title="Store up to 24 digits">
+ same => n,StoreDTMF(RX,testvar,24)
+ </example>
+ <example title="Disable digit collection">
+ same => n,StoreDTMF(remove)
+ </example>
</description>
</application>
***/
diff --git a/apps/app_mp3.c b/apps/app_mp3.c
index 8422240..888f21a 100644
--- a/apps/app_mp3.c
+++ b/apps/app_mp3.c
@@ -65,9 +65,11 @@
<description>
<para>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.</para>
+ <para>User can exit by pressing any key on the dialpad, or by hanging up.</para>
+ <example title="Play an MP3 playlist">
exten => 1234,1,MP3Player(/var/lib/asterisk/playlist.m3u)
- User can exit by pressing any key on the dialpad, or by hanging up.</para>
+ </example>
<para>This application does not automatically answer and should be preceeded by an
application such as Answer() or Progress().</para>
</description>
diff --git a/apps/app_queue.c b/apps/app_queue.c
index 4f5913a..b5cd163 100644
--- a/apps/app_queue.c
+++ b/apps/app_queue.c
@@ -376,7 +376,9 @@
<value name="NOTDYNAMIC" />
</variable>
</variablelist>
- <para>Example: RemoveQueueMember(techsupport,SIP/3000)</para>
+ <example title="Remove queue member">
+ same => n,RemoveQueueMember(techsupport,SIP/3000)
+ </example>
</description>
<see-also>
<ref type="application">Queue</ref>
@@ -421,7 +423,9 @@
<value name="NOTFOUND" />
</variable>
</variablelist>
- <para>Example: PauseQueueMember(,SIP/3000)</para>
+ <example title="Pause queue member">
+ same => n,PauseQueueMember(,SIP/3000)
+ </example>
</description>
<see-also>
<ref type="application">Queue</ref>
@@ -463,7 +467,9 @@
<value name="NOTFOUND" />
</variable>
</variablelist>
- <para>Example: UnpauseQueueMember(,SIP/3000)</para>
+ <example title="Unpause queue member">
+ same => n,UnpauseQueueMember(,SIP/3000)
+ </example>
</description>
<see-also>
<ref type="application">Queue</ref>
@@ -495,7 +501,9 @@
</syntax>
<description>
<para>Allows you to write your own events into the queue log.</para>
- <para>Example: QueueLog(101,${UNIQUEID},${AGENT},WENTONBREAK,600)</para>
+ <example title="Log custom queue event">
+ same => n,QueueLog(101,${UNIQUEID},${AGENT},WENTONBREAK,600)
+ </example>
</description>
<see-also>
<ref type="application">Queue</ref>
@@ -516,7 +524,7 @@
</application>
<application name="QueueUpdate" language="en_US">
<synopsis>
- 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.
</synopsis>
<syntax>
@@ -529,7 +537,9 @@
</syntax>
<description>
<para>Allows you to write Outbound events into the queue log.</para>
- <para>Example: exten => h,1,QueueUpdate(${QUEUE}, ${UNIQUEID}, ${AGENT}, ${DIALSTATUS}, ${ANSWEREDTIME}, ${DIALEDTIME} | ${DIALEDNUMBER})</para>
+ <example title="Write outbound event into queue log">
+ exten => h,1,QueueUpdate(${QUEUE}, ${UNIQUEID}, ${AGENT}, ${DIALSTATUS}, ${ANSWEREDTIME}, ${DIALEDTIME} | ${DIALEDNUMBER})
+ </example>
</description>
</application>
<function name="QUEUE_VARIABLES" language="en_US">
diff --git a/apps/app_waitforsilence.c b/apps/app_waitforsilence.c
index 52248ac..9820de2 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 <dave at popvox.com>
*
@@ -78,11 +75,15 @@
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>
+ <example title="Wait for half a second of silence, twice">
+ same => n,WaitForSilence(500,2)
+ </example>
+ <example title="Wait for one second of silence, once">
+ same => n,WaitForSilence(1000)
+ </example>
+ <example title="Wait for 300 ms of silence, 3 times, and returns after 10 seconds, even if no silence detected">
+ same => n,WaitForSilence(300,3,10)
+ </example>
<para>Sets the channel variable <variable>WAITSTATUS</variable> to one of these values:</para>
<variablelist>
<variable name="WAITSTATUS">
diff --git a/channels/chan_sip.c b/channels/chan_sip.c
index fe0a07f..66d9a6e 100644
--- a/channels/chan_sip.c
+++ b/channels/chan_sip.c
@@ -337,17 +337,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.</para>
- <para>For example you have added these 2 headers:</para>
- <para>SIPAddHeader(P-Asserted-Identity: sip:foo at bar);</para>
- <para>SIPAddHeader(P-Preferred-Identity: sip:bar at foo);</para>
- <para></para>
- <para>// remove all headers</para>
- <para>SIPRemoveHeader();</para>
- <para>// remove all P- headers</para>
- <para>SIPRemoveHeader(P-);</para>
- <para>// remove only the PAI header (note the : at the end)</para>
- <para>SIPRemoveHeader(P-Asserted-Identity:);</para>
- <para></para>
+ <example title="Add 2 headers">
+ same => n,SIPAddHeader(P-Asserted-Identity: sip:foo at bar)
+ same => n,SIPAddHeader(P-Preferred-Identity: sip:bar at foo)
+ </example>
+ <example title="Remove all headers">
+ same => n,SIPRemoveHeader()
+ </example>
+ <example title="Remove all P- headers">
+ same => n,SIPRemoveHeader(P-)
+ </example>
+ <example title="Remove only the PAI header (note the : at the end)">
+ same => n,SIPRemoveHeader(P-Asserted-Identity:)
+ </example>
<para>Always returns <literal>0</literal>.</para>
</description>
</application>
diff --git a/funcs/func_devstate.c b/funcs/func_devstate.c
index e6159e9..d09f9d8 100644
--- a/funcs/func_devstate.c
+++ b/funcs/func_devstate.c
@@ -90,8 +90,10 @@
</syntax>
<description>
<para>The HINT function can be used to retrieve the list of devices that are
- mapped to a dialplan hint. For example:</para>
- <para>NoOp(Hint for Extension 1234 is ${HINT(1234)})</para>
+ mapped to a dialplan hint.</para>
+ <example title="Hint for extension 1234">
+ same => n,NoOp(Hint for Extension 1234 is ${HINT(1234)})
+ </example>
</description>
</function>
***/
diff --git a/res/res_agi.c b/res/res_agi.c
index 631c9b8..8bdb7ed 100644
--- a/res/res_agi.c
+++ b/res/res_agi.c
@@ -1185,21 +1185,17 @@
after a channel hangup is detected, set the <variable>AGIEXITONHANGUP</variable>
variable to <literal>yes</literal>.</para>
</note>
- <example title="AGI invocation examples">
- ; 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)
+ <example title="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})
+ </example>
+ <example title="Start the AGI script my-cool-script.sh located in the astagidir directory, specified in asterisk.conf">
+ same => n,AGI(my-cool-script.sh)
+ </example>
+ <example title="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)
+ </example>
+ <example title="Start AsyncAGI">
+ same => n,AGI(agi:async)
</example>
<para>This application sets the following channel variable upon completion:</para>
<variablelist>
diff --git a/res/res_xmpp.c b/res/res_xmpp.c
index 8db0da8..2f1e0eb 100644
--- a/res/res_xmpp.c
+++ b/res/res_xmpp.c
@@ -84,9 +84,12 @@
<para>Sends the content of <replaceable>message</replaceable> as text message
from the given <replaceable>account</replaceable> to the buddy identified by
<replaceable>jid</replaceable></para>
- <para>Example: JabberSend(asterisk,bob at domain.com,Hello world) sends "Hello world"
- to <replaceable>bob at domain.com</replaceable> as an XMPP message from the account
+ <para>The example below sends "Hello world" to
+ <replaceable>bob at domain.com</replaceable> as an XMPP message from the account
<replaceable>asterisk</replaceable>, configured in xmpp.conf.</para>
+ <example title="Send 'Hello world' to Bob">
+ same => n,JabberSend(asterisk,bob at domain.com,Hello world)
+ </example>
</description>
<see-also>
<ref type="function" module="res_xmpp">JABBER_STATUS</ref>
@@ -113,9 +116,12 @@
<description>
<para>Receives a text message on the given <replaceable>account</replaceable>
from the buddy identified by <replaceable>jid</replaceable> and returns the contents.</para>
- <para>Example: ${JABBER_RECEIVE(asterisk,bob at domain.com)} returns an XMPP message
- sent from <replaceable>bob at domain.com</replaceable> (or nothing in case of a time out), to
+ <para>The example below returns an XMPP message sent from
+ <replaceable>bob at domain.com</replaceable> (or nothing in case of a time out), to
the <replaceable>asterisk</replaceable> XMPP account configured in xmpp.conf.</para>
+ <example title="Receive a message">
+ same => n,Set(msg=${JABBER_RECEIVE(asterisk,bob at domain.com)})
+ </example>
</description>
<see-also>
<ref type="function" module="res_xmpp">JABBER_STATUS</ref>
--
To view, visit https://gerrit.asterisk.org/c/asterisk/+/17608
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings
Gerrit-Project: asterisk
Gerrit-Branch: 18
Gerrit-Change-Id: I9acb6cc5faf1d220e73c6dd28592371d768d279b
Gerrit-Change-Number: 17608
Gerrit-PatchSet: 1
Gerrit-Owner: N A <mail at interlinked.x10host.com>
Gerrit-Reviewer: Friendly Automation
Gerrit-Reviewer: Kevin Harwell <kharwell at digium.com>
Gerrit-MessageType: merged
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20211202/4e0c207c/attachment-0001.html>
More information about the asterisk-code-review
mailing list