Skip to content

Commit

Permalink
xmldocs: Improve examples.
Browse files Browse the repository at this point in the history 
Use example tags instead of regular para tags
where possible.

ASTERISK-30090

Change-Id: Iada8bbfda08f30b118cedf2d040bbb21e4966ec5
  • Loading branch information
@InterLinked1 @jcolp
InterLinked1 authored and jcolp committed Jun 9, 2022
1 parent 31dc28a commit 51d262a
Show file tree
Hide file tree
Showing 23 changed files with 353 additions and 243 deletions.
26 changes: 16 additions & 10 deletions apps/app_confbridge.c
View file
Expand Up @@ -198,23 +198,29 @@
<para>---- Example 1 ----</para>
<para>In this example the custom user profile set on the channel will
automatically be used by the ConfBridge application.</para>
<para>exten => 1,1,Answer()</para>
<example title="Example 1">
exten => 1,1,Answer()
</example>
<para>; In this example the effect of the following line is</para>
<para>; implied:</para>
<para>; same => n,Set(CONFBRIDGE(user,template)=default_user)</para>
<para>same => n,Set(CONFBRIDGE(user,announce_join_leave)=yes)</para>
<para>same => n,Set(CONFBRIDGE(user,startmuted)=yes)</para>
<para>same => n,ConfBridge(1) </para>
<example title="Example 1b">
same => n,Set(CONFBRIDGE(user,template)=default_user)
same => n,Set(CONFBRIDGE(user,announce_join_leave)=yes)
same => n,Set(CONFBRIDGE(user,startmuted)=yes)
same => n,ConfBridge(1)
</example>
<para>---- Example 2 ----</para>
<para>This example shows how to use a predefined user profile in
<filename>confbridge.conf</filename> as a template for a dynamic profile.
Here we make an admin/marked user out of the <literal>my_user</literal>
profile that you define in <filename>confbridge.conf</filename>.</para>
<para>exten => 1,1,Answer()</para>
<para>same => n,Set(CONFBRIDGE(user,template)=my_user)</para>
<para>same => n,Set(CONFBRIDGE(user,admin)=yes)</para>
<para>same => n,Set(CONFBRIDGE(user,marked)=yes)</para>
<para>same => n,ConfBridge(1)</para>
<example title="Example 2">
exten => 1,1,Answer()
same => n,Set(CONFBRIDGE(user,template)=my_user)
same => n,Set(CONFBRIDGE(user,admin)=yes)
same => n,Set(CONFBRIDGE(user,marked)=yes)
same => n,ConfBridge(1)
</example>
</description>
</function>
<function name="CONFBRIDGE_INFO" language="en_US">
Expand Down
4 changes: 3 additions & 1 deletion funcs/func_cdr.c
View file
Expand Up @@ -161,7 +161,9 @@
<note><para>CDRs can only be modified before the bridge between two channels is
torn down. For example, CDRs may not be modified after the <literal>Dial</literal>
application has returned.</para></note>
<para>Example: exten => 1,1,Set(CDR(userfield)=test)</para>
<example title="Set the userfield">
exten => 1,1,Set(CDR(userfield)=test)
</example>
</description>
</function>
<function name="CDR_PROP" language="en_US">
Expand Down
9 changes: 5 additions & 4 deletions funcs/func_dialgroup.c
View file
Expand Up @@ -67,10 +67,11 @@
fallback to a queue when the front line people are busy or unavailable, but
you still want front line people to log in and out of that group, just like
a queue.</para>
<para>Example:</para>
<para>exten => 1,1,Set(DIALGROUP(mygroup,add)=SIP/10)</para>
<para>exten => 1,n,Set(DIALGROUP(mygroup,add)=SIP/20)</para>
<para>exten => 1,n,Dial(${DIALGROUP(mygroup)})</para>
<example title="Add 2 endpoints to a dial group">
exten => 1,1,Set(DIALGROUP(mygroup,add)=SIP/10)
same => n,Set(DIALGROUP(mygroup,add)=SIP/20)
same => n,Dial(${DIALGROUP(mygroup)})
</example>
</description>
</function>
***/
Expand Down
89 changes: 51 additions & 38 deletions funcs/func_env.c
View file
Expand Up @@ -178,48 +178,61 @@
<description>
<para>Read and write text file in character and line mode.</para>
<para>Examples:</para>
<para/>
<para>Read mode (byte):</para>
<para> ;reads the entire content of the file.</para>
<para> Set(foo=${FILE(/tmp/test.txt)})</para>
<para> ;reads from the 11th byte to the end of the file (i.e. skips the first 10).</para>
<para> Set(foo=${FILE(/tmp/test.txt,10)})</para>
<para> ;reads from the 11th to 20th byte in the file (i.e. skip the first 10, then read 10 bytes).</para>
<para> Set(foo=${FILE(/tmp/test.txt,10,10)})</para>
<para/>
<example title="Reads the entire content of the file">
same => n,Set(foo=${FILE(/tmp/test.txt)})
</example>
<example title="Reads from the 11th byte to the end of the file (i.e. skips the first 10)">
same => n,Set(foo=${FILE(/tmp/test.txt,10)})
</example>
<example title="Reads from the 11th to 20th byte in the file (i.e. skip the first 10, then read 10 bytes)">
same => n,Set(foo=${FILE(/tmp/test.txt,10,10)})
</example>
<para>Read mode (line):</para>
<para> ; reads the 3rd line of the file.</para>
<para> Set(foo=${FILE(/tmp/test.txt,3,1,l)})</para>
<para> ; reads the 3rd and 4th lines of the file.</para>
<para> Set(foo=${FILE(/tmp/test.txt,3,2,l)})</para>
<para> ; reads from the third line to the end of the file.</para>
<para> Set(foo=${FILE(/tmp/test.txt,3,,l)})</para>
<para> ; reads the last three lines of the file.</para>
<para> Set(foo=${FILE(/tmp/test.txt,-3,,l)})</para>
<para> ; reads the 3rd line of a DOS-formatted file.</para>
<para> Set(foo=${FILE(/tmp/test.txt,3,1,l,d)})</para>
<para/>
<example title="Reads the 3rd line of the file">
same => n,Set(foo=${FILE(/tmp/test.txt,3,1,l)})
</example>
<example title="Reads the 3rd and 4th lines of the file">
same => n,Set(foo=${FILE(/tmp/test.txt,3,2,l)})
</example>
<example title="Reads from the third line to the end of the file">
same => n,Set(foo=${FILE(/tmp/test.txt,3,,l)})
</example>
<example title="Reads the last three lines of the file">
same => n,Set(foo=${FILE(/tmp/test.txt,-3,,l)})
</example>
<example title="Reads the 3rd line of a DOS-formatted file">
same => n,Set(foo=${FILE(/tmp/test.txt,3,1,l,d)})
</example>
<para>Write mode (byte):</para>
<para> ; truncate the file and write "bar"</para>
<para> Set(FILE(/tmp/test.txt)=bar)</para>
<para> ; Append "bar"</para>
<para> Set(FILE(/tmp/test.txt,,,a)=bar)</para>
<para> ; Replace the first byte with "bar" (replaces 1 character with 3)</para>
<para> Set(FILE(/tmp/test.txt,0,1)=bar)</para>
<para> ; Replace 10 bytes beginning at the 21st byte of the file with "bar"</para>
<para> Set(FILE(/tmp/test.txt,20,10)=bar)</para>
<para> ; Replace all bytes from the 21st with "bar"</para>
<para> Set(FILE(/tmp/test.txt,20)=bar)</para>
<para> ; Insert "bar" after the 4th character</para>
<para> Set(FILE(/tmp/test.txt,4,0)=bar)</para>
<para/>
<example title="Truncate the file and write bar">
same => n,Set(FILE(/tmp/test.txt)=bar)
</example>
<example title="Append bar">
same => n,Set(FILE(/tmp/test.txt,,,a)=bar)
</example>
<example title="Replace the first byte with bar (replaces 1 character with 3)">
same => n,Set(FILE(/tmp/test.txt,0,1)=bar)
</example>
<example title="Replace 10 bytes beginning at the 21st byte of the file with bar">
same => n,Set(FILE(/tmp/test.txt,20,10)=bar)
</example>
<example title="Replace all bytes from the 21st with bar">
same => n,Set(FILE(/tmp/test.txt,20)=bar)
</example>
<example title="Insert bar after the 4th character">
same => n,Set(FILE(/tmp/test.txt,4,0)=bar)
</example>
<para>Write mode (line):</para>
<para> ; Replace the first line of the file with "bar"</para>
<para> Set(FILE(/tmp/foo.txt,0,1,l)=bar)</para>
<para> ; Replace the last line of the file with "bar"</para>
<para> Set(FILE(/tmp/foo.txt,-1,,l)=bar)</para>
<para> ; Append "bar" to the file with a newline</para>
<para> Set(FILE(/tmp/foo.txt,,,al)=bar)</para>
<example title="Replace the first line of the file with bar">
same => n,Set(FILE(/tmp/foo.txt,0,1,l)=bar)
</example>
<example title="Replace the last line of the file with bar">
same => n,Set(FILE(/tmp/foo.txt,-1,,l)=bar)
</example>
<example title="Append bar to the file with a newline">
same => n,Set(FILE(/tmp/foo.txt,,,al)=bar)
</example>
<note>
<para>If <literal>live_dangerously</literal> in <literal>asterisk.conf</literal>
is set to <literal>no</literal>, this function can only be executed from the
Expand Down
12 changes: 9 additions & 3 deletions funcs/func_frame_drop.c
View file
Expand Up @@ -91,9 +91,15 @@
</syntax>
<description>
<para>Examples:</para>
<para>exten => 1,1,Set(FRAME_DROP(TX)=DTMF_BEGIN,DTMF_END); drop only DTMF frames towards this channel.</para>
<para>exten => 1,1,Set(FRAME_DROP(TX)=ANSWER); drop only ANSWER CONTROL frames towards this channel.</para>
<para>exten => 1,1,Set(FRAME_DROP(RX)=DTMF_BEGIN,DTMF_END); drop only DTMF frames received on this channel.</para>
<example title="Drop only DTMF frames towards this channel">
exten => 1,1,Set(FRAME_DROP(TX)=DTMF_BEGIN,DTMF_END)
</example>
<example title="Drop only Answer control frames towards this channel">
exten => 1,1,Set(FRAME_DROP(TX)=ANSWER)
</example>
<example title="Drop only DTMF frames received on this channel">
exten => 1,1,Set(FRAME_DROP(RX)=DTMF_BEGIN,DTMF_END)
</example>
</description>
</function>
***/
Expand Down
12 changes: 9 additions & 3 deletions funcs/func_frame_trace.c
View file
Expand Up @@ -69,9 +69,15 @@
</syntax>
<description>
<para>Examples:</para>
<para>exten => 1,1,Set(FRAME_TRACE(white)=DTMF_BEGIN,DTMF_END); view only DTMF frames. </para>
<para>exten => 1,1,Set(FRAME_TRACE()=DTMF_BEGIN,DTMF_END); view only DTMF frames. </para>
<para>exten => 1,1,Set(FRAME_TRACE(black)=DTMF_BEGIN,DTMF_END); view everything except DTMF frames. </para>
<example title="View only DTMF frames">
exten => 1,1,Set(FRAME_TRACE(white)=DTMF_BEGIN,DTMF_END)
</example>
<example title="View only DTMF frames">
exten => 1,1,Set(FRAME_TRACE()=DTMF_BEGIN,DTMF_END)
</example>
<example title="View everything except DTMF frames">
exten => 1,1,Set(FRAME_TRACE(black)=DTMF_BEGIN,DTMF_END)
</example>
</description>
</function>
***/
Expand Down
25 changes: 16 additions & 9 deletions funcs/func_math.c
View file
Expand Up @@ -71,7 +71,9 @@
<description>
<para>Performs mathematical functions based on two parameters and an operator. The returned
value type is <replaceable>type</replaceable></para>
<para>Example: Set(i=${MATH(123%16,int)}) - sets var i=11</para>
<example title="Sets var i to 11">
same => n,Set(i=${MATH(123%16,int)})
</example>
</description>
</function>
<function name="INC" language="en_US">
Expand Down Expand Up @@ -104,8 +106,10 @@
</syntax>
<description>
<para>Decrements the value of a variable, while returning the updated value to the dialplan</para>
<para>Example: DEC(MyVAR) - Decrements MyVar</para>
<para>Note: DEC(${MyVAR}) - Is wrong, as DEC expects the variable name, not its value</para>
<example title="Decrements MyVAR">
same => n,NoOp(${DEC(MyVAR)})
</example>
<note><para>DEC(${MyVAR}) is wrong, as DEC expects the variable name, not its value</para></note>
</description>
</function>
<function name="MIN" language="en_US">
Expand All @@ -123,8 +127,9 @@
</syntax>
<description>
<para>Returns the minimum of two numbers <replaceable>num1</replaceable> and <replaceable>num2</replaceable>.</para>
<para>Example: Set(min=${MIN(7,4)});
Sets the min variable equal to 4.</para>
<example title="Sets the min variable equal to 4">
same => n,Set(min=${MIN(7,4)})
</example>
</description>
</function>
<function name="MAX" language="en_US">
Expand All @@ -142,8 +147,9 @@
</syntax>
<description>
<para>Returns the maximum of two numbers <replaceable>num1</replaceable> and <replaceable>num2</replaceable>.</para>
<para>Example: Set(max=${MAX(4,7)});
Sets the max variable equal to 7.</para>
<example title="Sets the max variable equal to 13">
same => n,Set(max=${MAX(4,7)})
</example>
</description>
</function>
<function name="ABS" language="en_US">
Expand All @@ -160,8 +166,9 @@
</syntax>
<description>
<para>Returns the absolute value of a number <replaceable>num</replaceable>.</para>
<para>Example: Set(absval=${ABS(-13)});
Sets the absval variable equal to 13.</para>
<example title="Sets the absval variable equal to 13">
same => n,Set(absval=${ABS(-13)})
</example>
</description>
</function>
***/
Expand Down
8 changes: 6 additions & 2 deletions funcs/func_odbc.c
View file
Expand Up @@ -93,7 +93,9 @@
<description>
<para>Used in SQL templates to escape data which may contain single ticks
<literal>'</literal> which are otherwise used to delimit data.</para>
<para>Example: SELECT foo FROM bar WHERE baz='${SQL_ESC(${ARG1})}'</para>
<example title="Escape example">
SELECT foo FROM bar WHERE baz='${SQL_ESC(${ARG1})}'
</example>
</description>
</function>
<function name="SQL_ESC_BACKSLASHES" language="en_US">
Expand All @@ -106,7 +108,9 @@
<description>
<para>Used in SQL templates to escape data which may contain backslashes
<literal>\</literal> which are otherwise used to escape data.</para>
<para>Example: SELECT foo FROM bar WHERE baz='${SQL_ESC(${SQL_ESC_BACKSLASHES(${ARG1})})}'</para>
<example title="Escape with backslashes example">
SELECT foo FROM bar WHERE baz='${SQL_ESC(${SQL_ESC_BACKSLASHES(${ARG1})})}'
</example>
</description>
</function>
***/
Expand Down
18 changes: 9 additions & 9 deletions funcs/func_periodic_hook.c
View file
Expand Up @@ -67,15 +67,15 @@
<para>For example, you could use this function to enable playing
a periodic <literal>beep</literal> sound in a call.</para>
<para/>
<para>To turn on:</para>
<para> Set(BEEPID=${PERIODIC_HOOK(hooks,beep,180)})</para>
<para/>
<para>To turn off:</para>
<para> Set(PERIODIC_HOOK(${BEEPID})=off)</para>
<para/>
<para>To turn back on again later:</para>
<para>Set(PERIODIC_HOOK(${BEEPID})=on)</para>
<para/>
<example title="To turn on">
same => n,Set(BEEPID=${PERIODIC_HOOK(hooks,beep,180)})
</example>
<example title="To turn off">
same => n,Set(PERIODIC_HOOK(${BEEPID})=off)
</example>
<example title="To turn back on again later">
same => n,Set(PERIODIC_HOOK(${BEEPID})=on)
</example>
<para>It is important to note that the hook does not actually
run on the channel itself. It runs asynchronously on a new channel.
Any audio generated by the hook gets injected into the call for
Expand Down
33 changes: 24 additions & 9 deletions funcs/func_pitchshift.c
View file
Expand Up @@ -97,15 +97,30 @@
</syntax>
<description>
<para>Examples:</para>
<para>exten => 1,1,Set(PITCH_SHIFT(tx)=highest); raises pitch an octave </para>
<para>exten => 1,1,Set(PITCH_SHIFT(rx)=higher) ; raises pitch more </para>
<para>exten => 1,1,Set(PITCH_SHIFT(both)=high) ; raises pitch </para>
<para>exten => 1,1,Set(PITCH_SHIFT(rx)=low) ; lowers pitch </para>
<para>exten => 1,1,Set(PITCH_SHIFT(tx)=lower) ; lowers pitch more </para>
<para>exten => 1,1,Set(PITCH_SHIFT(both)=lowest) ; lowers pitch an octave </para>
<para>exten => 1,1,Set(PITCH_SHIFT(rx)=0.8) ; lowers pitch </para>
<para>exten => 1,1,Set(PITCH_SHIFT(tx)=1.5) ; raises pitch </para>
<example title="Raises pitch an octave">
exten => 1,1,Set(PITCH_SHIFT(tx)=highest)
</example>
<example title="Raises pitch more">
exten => 1,1,Set(PITCH_SHIFT(rx)=higher)
</example>
<example title="Raises pitch">
exten => 1,1,Set(PITCH_SHIFT(both)=high)
</example>
<example title="Lowers pitch">
exten => 1,1,Set(PITCH_SHIFT(rx)=low)
</example>
<example title="Lowers pitch more">
exten => 1,1,Set(PITCH_SHIFT(tx)=lower)
</example>
<example title="Lowers pitch an octave">
exten => 1,1,Set(PITCH_SHIFT(both)=lowest)
</example>
<example title="Lowers pitch">
exten => 1,1,Set(PITCH_SHIFT(rx)=0.8)
</example>
<example title="Raises pitch">
exten => 1,1,Set(PITCH_SHIFT(tx)=1.5)
</example>
</description>
</function>
***/
Expand Down
5 changes: 3 additions & 2 deletions funcs/func_rand.c
View file
Expand Up @@ -49,8 +49,9 @@
<para>Choose a random number between <replaceable>min</replaceable> and <replaceable>max</replaceable>.
<replaceable>min</replaceable> defaults to <literal>0</literal>, if not specified, while <replaceable>max</replaceable> defaults
to <literal>RAND_MAX</literal> (2147483647 on many systems).</para>
<para>Example: Set(junky=${RAND(1,8)});
Sets junky to a random number between 1 and 8, inclusive.</para>
<example title="Set random number between 1 and 8, inclusive">
exten => s,1,Set(junky=${RAND(1,8)})
</example>
</description>
</function>
***/
Expand Down
8 changes: 5 additions & 3 deletions funcs/func_sha1.c
View file
Expand Up @@ -45,9 +45,11 @@
</syntax>
<description>
<para>Generate a SHA1 digest via the SHA1 algorythm.</para>
<para>Example: Set(sha1hash=${SHA1(junky)})</para>
<para>Sets the asterisk variable sha1hash to the string <literal>60fa5675b9303eb62f99a9cd47f9f5837d18f9a0</literal>
which is known as his hash</para>
<example title="Set sha1hash variable to SHA1 hash of junky">
exten => s,1,Set(sha1hash=${SHA1(junky)})
</example>
<para>The example above sets the asterisk variable sha1hash to the string <literal>60fa5675b9303eb62f99a9cd47f9f5837d18f9a0</literal>
which is known as its hash</para>
</description>
</function>
***/
Expand Down
4 changes: 3 additions & 1 deletion funcs/func_shell.c
View file
Expand Up @@ -91,7 +91,9 @@ static int shell_helper(struct ast_channel *chan, const char *cmd, char *data,
</syntax>
<description>
<para>Collects the output generated by a command executed by the system shell</para>
<para>Example: <literal>Set(foo=${SHELL(echo bar)})</literal></para>
<example title="Shell example">
exten => s,1,Set(foo=${SHELL(echo bar)})
</example>
<note>
<para>The command supplied to this function will be executed by the
system's shell, typically specified in the SHELL environment variable. There
Expand Down

0 comments on commit 51d262a

Please sign in to comment.