Skip to content

Commit 51d262a

Browse files
InterLinked1jcolp
InterLinked1
authored and
jcolp
committed
xmldocs: Improve examples.
Use example tags instead of regular para tags where possible. ASTERISK-30090 Change-Id: Iada8bbfda08f30b118cedf2d040bbb21e4966ec5
1 parent 31dc28a commit 51d262a

23 files changed

+353
-243
lines changed

‎apps/app_confbridge.c

+16-10
Original file line numberDiff line numberDiff line change
@@ -198,23 +198,29 @@
198198
<para>---- Example 1 ----</para>
199199
<para>In this example the custom user profile set on the channel will
200200
automatically be used by the ConfBridge application.</para>
201-
<para>exten => 1,1,Answer()</para>
201+
<example title="Example 1">
202+
exten => 1,1,Answer()
203+
</example>
202204
<para>; In this example the effect of the following line is</para>
203205
<para>; implied:</para>
204-
<para>; same => n,Set(CONFBRIDGE(user,template)=default_user)</para>
205-
<para>same => n,Set(CONFBRIDGE(user,announce_join_leave)=yes)</para>
206-
<para>same => n,Set(CONFBRIDGE(user,startmuted)=yes)</para>
207-
<para>same => n,ConfBridge(1) </para>
206+
<example title="Example 1b">
207+
same => n,Set(CONFBRIDGE(user,template)=default_user)
208+
same => n,Set(CONFBRIDGE(user,announce_join_leave)=yes)
209+
same => n,Set(CONFBRIDGE(user,startmuted)=yes)
210+
same => n,ConfBridge(1)
211+
</example>
208212
<para>---- Example 2 ----</para>
209213
<para>This example shows how to use a predefined user profile in
210214
<filename>confbridge.conf</filename> as a template for a dynamic profile.
211215
Here we make an admin/marked user out of the <literal>my_user</literal>
212216
profile that you define in <filename>confbridge.conf</filename>.</para>
213-
<para>exten => 1,1,Answer()</para>
214-
<para>same => n,Set(CONFBRIDGE(user,template)=my_user)</para>
215-
<para>same => n,Set(CONFBRIDGE(user,admin)=yes)</para>
216-
<para>same => n,Set(CONFBRIDGE(user,marked)=yes)</para>
217-
<para>same => n,ConfBridge(1)</para>
217+
<example title="Example 2">
218+
exten => 1,1,Answer()
219+
same => n,Set(CONFBRIDGE(user,template)=my_user)
220+
same => n,Set(CONFBRIDGE(user,admin)=yes)
221+
same => n,Set(CONFBRIDGE(user,marked)=yes)
222+
same => n,ConfBridge(1)
223+
</example>
218224
</description>
219225
</function>
220226
<function name="CONFBRIDGE_INFO" language="en_US">

‎funcs/func_cdr.c

+3-1
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,9 @@
161161
<note><para>CDRs can only be modified before the bridge between two channels is
162162
torn down. For example, CDRs may not be modified after the <literal>Dial</literal>
163163
application has returned.</para></note>
164-
<para>Example: exten => 1,1,Set(CDR(userfield)=test)</para>
164+
<example title="Set the userfield">
165+
exten => 1,1,Set(CDR(userfield)=test)
166+
</example>
165167
</description>
166168
</function>
167169
<function name="CDR_PROP" language="en_US">

‎funcs/func_dialgroup.c

+5-4
Original file line numberDiff line numberDiff line change
@@ -67,10 +67,11 @@
6767
fallback to a queue when the front line people are busy or unavailable, but
6868
you still want front line people to log in and out of that group, just like
6969
a queue.</para>
70-
<para>Example:</para>
71-
<para>exten => 1,1,Set(DIALGROUP(mygroup,add)=SIP/10)</para>
72-
<para>exten => 1,n,Set(DIALGROUP(mygroup,add)=SIP/20)</para>
73-
<para>exten => 1,n,Dial(${DIALGROUP(mygroup)})</para>
70+
<example title="Add 2 endpoints to a dial group">
71+
exten => 1,1,Set(DIALGROUP(mygroup,add)=SIP/10)
72+
same => n,Set(DIALGROUP(mygroup,add)=SIP/20)
73+
same => n,Dial(${DIALGROUP(mygroup)})
74+
</example>
7475
</description>
7576
</function>
7677
***/

‎funcs/func_env.c

+51-38
Original file line numberDiff line numberDiff line change
@@ -178,48 +178,61 @@
178178
<description>
179179
<para>Read and write text file in character and line mode.</para>
180180
<para>Examples:</para>
181-
<para/>
182181
<para>Read mode (byte):</para>
183-
<para> ;reads the entire content of the file.</para>
184-
<para> Set(foo=${FILE(/tmp/test.txt)})</para>
185-
<para> ;reads from the 11th byte to the end of the file (i.e. skips the first 10).</para>
186-
<para> Set(foo=${FILE(/tmp/test.txt,10)})</para>
187-
<para> ;reads from the 11th to 20th byte in the file (i.e. skip the first 10, then read 10 bytes).</para>
188-
<para> Set(foo=${FILE(/tmp/test.txt,10,10)})</para>
189-
<para/>
182+
<example title="Reads the entire content of the file">
183+
same => n,Set(foo=${FILE(/tmp/test.txt)})
184+
</example>
185+
<example title="Reads from the 11th byte to the end of the file (i.e. skips the first 10)">
186+
same => n,Set(foo=${FILE(/tmp/test.txt,10)})
187+
</example>
188+
<example title="Reads from the 11th to 20th byte in the file (i.e. skip the first 10, then read 10 bytes)">
189+
same => n,Set(foo=${FILE(/tmp/test.txt,10,10)})
190+
</example>
190191
<para>Read mode (line):</para>
191-
<para> ; reads the 3rd line of the file.</para>
192-
<para> Set(foo=${FILE(/tmp/test.txt,3,1,l)})</para>
193-
<para> ; reads the 3rd and 4th lines of the file.</para>
194-
<para> Set(foo=${FILE(/tmp/test.txt,3,2,l)})</para>
195-
<para> ; reads from the third line to the end of the file.</para>
196-
<para> Set(foo=${FILE(/tmp/test.txt,3,,l)})</para>
197-
<para> ; reads the last three lines of the file.</para>
198-
<para> Set(foo=${FILE(/tmp/test.txt,-3,,l)})</para>
199-
<para> ; reads the 3rd line of a DOS-formatted file.</para>
200-
<para> Set(foo=${FILE(/tmp/test.txt,3,1,l,d)})</para>
201-
<para/>
192+
<example title="Reads the 3rd line of the file">
193+
same => n,Set(foo=${FILE(/tmp/test.txt,3,1,l)})
194+
</example>
195+
<example title="Reads the 3rd and 4th lines of the file">
196+
same => n,Set(foo=${FILE(/tmp/test.txt,3,2,l)})
197+
</example>
198+
<example title="Reads from the third line to the end of the file">
199+
same => n,Set(foo=${FILE(/tmp/test.txt,3,,l)})
200+
</example>
201+
<example title="Reads the last three lines of the file">
202+
same => n,Set(foo=${FILE(/tmp/test.txt,-3,,l)})
203+
</example>
204+
<example title="Reads the 3rd line of a DOS-formatted file">
205+
same => n,Set(foo=${FILE(/tmp/test.txt,3,1,l,d)})
206+
</example>
202207
<para>Write mode (byte):</para>
203-
<para> ; truncate the file and write "bar"</para>
204-
<para> Set(FILE(/tmp/test.txt)=bar)</para>
205-
<para> ; Append "bar"</para>
206-
<para> Set(FILE(/tmp/test.txt,,,a)=bar)</para>
207-
<para> ; Replace the first byte with "bar" (replaces 1 character with 3)</para>
208-
<para> Set(FILE(/tmp/test.txt,0,1)=bar)</para>
209-
<para> ; Replace 10 bytes beginning at the 21st byte of the file with "bar"</para>
210-
<para> Set(FILE(/tmp/test.txt,20,10)=bar)</para>
211-
<para> ; Replace all bytes from the 21st with "bar"</para>
212-
<para> Set(FILE(/tmp/test.txt,20)=bar)</para>
213-
<para> ; Insert "bar" after the 4th character</para>
214-
<para> Set(FILE(/tmp/test.txt,4,0)=bar)</para>
215-
<para/>
208+
<example title="Truncate the file and write bar">
209+
same => n,Set(FILE(/tmp/test.txt)=bar)
210+
</example>
211+
<example title="Append bar">
212+
same => n,Set(FILE(/tmp/test.txt,,,a)=bar)
213+
</example>
214+
<example title="Replace the first byte with bar (replaces 1 character with 3)">
215+
same => n,Set(FILE(/tmp/test.txt,0,1)=bar)
216+
</example>
217+
<example title="Replace 10 bytes beginning at the 21st byte of the file with bar">
218+
same => n,Set(FILE(/tmp/test.txt,20,10)=bar)
219+
</example>
220+
<example title="Replace all bytes from the 21st with bar">
221+
same => n,Set(FILE(/tmp/test.txt,20)=bar)
222+
</example>
223+
<example title="Insert bar after the 4th character">
224+
same => n,Set(FILE(/tmp/test.txt,4,0)=bar)
225+
</example>
216226
<para>Write mode (line):</para>
217-
<para> ; Replace the first line of the file with "bar"</para>
218-
<para> Set(FILE(/tmp/foo.txt,0,1,l)=bar)</para>
219-
<para> ; Replace the last line of the file with "bar"</para>
220-
<para> Set(FILE(/tmp/foo.txt,-1,,l)=bar)</para>
221-
<para> ; Append "bar" to the file with a newline</para>
222-
<para> Set(FILE(/tmp/foo.txt,,,al)=bar)</para>
227+
<example title="Replace the first line of the file with bar">
228+
same => n,Set(FILE(/tmp/foo.txt,0,1,l)=bar)
229+
</example>
230+
<example title="Replace the last line of the file with bar">
231+
same => n,Set(FILE(/tmp/foo.txt,-1,,l)=bar)
232+
</example>
233+
<example title="Append bar to the file with a newline">
234+
same => n,Set(FILE(/tmp/foo.txt,,,al)=bar)
235+
</example>
223236
<note>
224237
<para>If <literal>live_dangerously</literal> in <literal>asterisk.conf</literal>
225238
is set to <literal>no</literal>, this function can only be executed from the

‎funcs/func_frame_drop.c

+9-3
Original file line numberDiff line numberDiff line change
@@ -91,9 +91,15 @@
9191
</syntax>
9292
<description>
9393
<para>Examples:</para>
94-
<para>exten => 1,1,Set(FRAME_DROP(TX)=DTMF_BEGIN,DTMF_END); drop only DTMF frames towards this channel.</para>
95-
<para>exten => 1,1,Set(FRAME_DROP(TX)=ANSWER); drop only ANSWER CONTROL frames towards this channel.</para>
96-
<para>exten => 1,1,Set(FRAME_DROP(RX)=DTMF_BEGIN,DTMF_END); drop only DTMF frames received on this channel.</para>
94+
<example title="Drop only DTMF frames towards this channel">
95+
exten => 1,1,Set(FRAME_DROP(TX)=DTMF_BEGIN,DTMF_END)
96+
</example>
97+
<example title="Drop only Answer control frames towards this channel">
98+
exten => 1,1,Set(FRAME_DROP(TX)=ANSWER)
99+
</example>
100+
<example title="Drop only DTMF frames received on this channel">
101+
exten => 1,1,Set(FRAME_DROP(RX)=DTMF_BEGIN,DTMF_END)
102+
</example>
97103
</description>
98104
</function>
99105
***/

‎funcs/func_frame_trace.c

+9-3
Original file line numberDiff line numberDiff line change
@@ -69,9 +69,15 @@
6969
</syntax>
7070
<description>
7171
<para>Examples:</para>
72-
<para>exten => 1,1,Set(FRAME_TRACE(white)=DTMF_BEGIN,DTMF_END); view only DTMF frames. </para>
73-
<para>exten => 1,1,Set(FRAME_TRACE()=DTMF_BEGIN,DTMF_END); view only DTMF frames. </para>
74-
<para>exten => 1,1,Set(FRAME_TRACE(black)=DTMF_BEGIN,DTMF_END); view everything except DTMF frames. </para>
72+
<example title="View only DTMF frames">
73+
exten => 1,1,Set(FRAME_TRACE(white)=DTMF_BEGIN,DTMF_END)
74+
</example>
75+
<example title="View only DTMF frames">
76+
exten => 1,1,Set(FRAME_TRACE()=DTMF_BEGIN,DTMF_END)
77+
</example>
78+
<example title="View everything except DTMF frames">
79+
exten => 1,1,Set(FRAME_TRACE(black)=DTMF_BEGIN,DTMF_END)
80+
</example>
7581
</description>
7682
</function>
7783
***/

‎funcs/func_math.c

+16-9
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,9 @@
7171
<description>
7272
<para>Performs mathematical functions based on two parameters and an operator. The returned
7373
value type is <replaceable>type</replaceable></para>
74-
<para>Example: Set(i=${MATH(123%16,int)}) - sets var i=11</para>
74+
<example title="Sets var i to 11">
75+
same => n,Set(i=${MATH(123%16,int)})
76+
</example>
7577
</description>
7678
</function>
7779
<function name="INC" language="en_US">
@@ -104,8 +106,10 @@
104106
</syntax>
105107
<description>
106108
<para>Decrements the value of a variable, while returning the updated value to the dialplan</para>
107-
<para>Example: DEC(MyVAR) - Decrements MyVar</para>
108-
<para>Note: DEC(${MyVAR}) - Is wrong, as DEC expects the variable name, not its value</para>
109+
<example title="Decrements MyVAR">
110+
same => n,NoOp(${DEC(MyVAR)})
111+
</example>
112+
<note><para>DEC(${MyVAR}) is wrong, as DEC expects the variable name, not its value</para></note>
109113
</description>
110114
</function>
111115
<function name="MIN" language="en_US">
@@ -123,8 +127,9 @@
123127
</syntax>
124128
<description>
125129
<para>Returns the minimum of two numbers <replaceable>num1</replaceable> and <replaceable>num2</replaceable>.</para>
126-
<para>Example: Set(min=${MIN(7,4)});
127-
Sets the min variable equal to 4.</para>
130+
<example title="Sets the min variable equal to 4">
131+
same => n,Set(min=${MIN(7,4)})
132+
</example>
128133
</description>
129134
</function>
130135
<function name="MAX" language="en_US">
@@ -142,8 +147,9 @@
142147
</syntax>
143148
<description>
144149
<para>Returns the maximum of two numbers <replaceable>num1</replaceable> and <replaceable>num2</replaceable>.</para>
145-
<para>Example: Set(max=${MAX(4,7)});
146-
Sets the max variable equal to 7.</para>
150+
<example title="Sets the max variable equal to 13">
151+
same => n,Set(max=${MAX(4,7)})
152+
</example>
147153
</description>
148154
</function>
149155
<function name="ABS" language="en_US">
@@ -160,8 +166,9 @@
160166
</syntax>
161167
<description>
162168
<para>Returns the absolute value of a number <replaceable>num</replaceable>.</para>
163-
<para>Example: Set(absval=${ABS(-13)});
164-
Sets the absval variable equal to 13.</para>
169+
<example title="Sets the absval variable equal to 13">
170+
same => n,Set(absval=${ABS(-13)})
171+
</example>
165172
</description>
166173
</function>
167174
***/

‎funcs/func_odbc.c

+6-2
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,9 @@
9393
<description>
9494
<para>Used in SQL templates to escape data which may contain single ticks
9595
<literal>'</literal> which are otherwise used to delimit data.</para>
96-
<para>Example: SELECT foo FROM bar WHERE baz='${SQL_ESC(${ARG1})}'</para>
96+
<example title="Escape example">
97+
SELECT foo FROM bar WHERE baz='${SQL_ESC(${ARG1})}'
98+
</example>
9799
</description>
98100
</function>
99101
<function name="SQL_ESC_BACKSLASHES" language="en_US">
@@ -106,7 +108,9 @@
106108
<description>
107109
<para>Used in SQL templates to escape data which may contain backslashes
108110
<literal>\</literal> which are otherwise used to escape data.</para>
109-
<para>Example: SELECT foo FROM bar WHERE baz='${SQL_ESC(${SQL_ESC_BACKSLASHES(${ARG1})})}'</para>
111+
<example title="Escape with backslashes example">
112+
SELECT foo FROM bar WHERE baz='${SQL_ESC(${SQL_ESC_BACKSLASHES(${ARG1})})}'
113+
</example>
110114
</description>
111115
</function>
112116
***/

‎funcs/func_periodic_hook.c

+9-9
Original file line numberDiff line numberDiff line change
@@ -67,15 +67,15 @@
6767
<para>For example, you could use this function to enable playing
6868
a periodic <literal>beep</literal> sound in a call.</para>
6969
<para/>
70-
<para>To turn on:</para>
71-
<para> Set(BEEPID=${PERIODIC_HOOK(hooks,beep,180)})</para>
72-
<para/>
73-
<para>To turn off:</para>
74-
<para> Set(PERIODIC_HOOK(${BEEPID})=off)</para>
75-
<para/>
76-
<para>To turn back on again later:</para>
77-
<para>Set(PERIODIC_HOOK(${BEEPID})=on)</para>
78-
<para/>
70+
<example title="To turn on">
71+
same => n,Set(BEEPID=${PERIODIC_HOOK(hooks,beep,180)})
72+
</example>
73+
<example title="To turn off">
74+
same => n,Set(PERIODIC_HOOK(${BEEPID})=off)
75+
</example>
76+
<example title="To turn back on again later">
77+
same => n,Set(PERIODIC_HOOK(${BEEPID})=on)
78+
</example>
7979
<para>It is important to note that the hook does not actually
8080
run on the channel itself. It runs asynchronously on a new channel.
8181
Any audio generated by the hook gets injected into the call for

‎funcs/func_pitchshift.c

+24-9
Original file line numberDiff line numberDiff line change
@@ -97,15 +97,30 @@
9797
</syntax>
9898
<description>
9999
<para>Examples:</para>
100-
<para>exten => 1,1,Set(PITCH_SHIFT(tx)=highest); raises pitch an octave </para>
101-
<para>exten => 1,1,Set(PITCH_SHIFT(rx)=higher) ; raises pitch more </para>
102-
<para>exten => 1,1,Set(PITCH_SHIFT(both)=high) ; raises pitch </para>
103-
<para>exten => 1,1,Set(PITCH_SHIFT(rx)=low) ; lowers pitch </para>
104-
<para>exten => 1,1,Set(PITCH_SHIFT(tx)=lower) ; lowers pitch more </para>
105-
<para>exten => 1,1,Set(PITCH_SHIFT(both)=lowest) ; lowers pitch an octave </para>
106-
107-
<para>exten => 1,1,Set(PITCH_SHIFT(rx)=0.8) ; lowers pitch </para>
108-
<para>exten => 1,1,Set(PITCH_SHIFT(tx)=1.5) ; raises pitch </para>
100+
<example title="Raises pitch an octave">
101+
exten => 1,1,Set(PITCH_SHIFT(tx)=highest)
102+
</example>
103+
<example title="Raises pitch more">
104+
exten => 1,1,Set(PITCH_SHIFT(rx)=higher)
105+
</example>
106+
<example title="Raises pitch">
107+
exten => 1,1,Set(PITCH_SHIFT(both)=high)
108+
</example>
109+
<example title="Lowers pitch">
110+
exten => 1,1,Set(PITCH_SHIFT(rx)=low)
111+
</example>
112+
<example title="Lowers pitch more">
113+
exten => 1,1,Set(PITCH_SHIFT(tx)=lower)
114+
</example>
115+
<example title="Lowers pitch an octave">
116+
exten => 1,1,Set(PITCH_SHIFT(both)=lowest)
117+
</example>
118+
<example title="Lowers pitch">
119+
exten => 1,1,Set(PITCH_SHIFT(rx)=0.8)
120+
</example>
121+
<example title="Raises pitch">
122+
exten => 1,1,Set(PITCH_SHIFT(tx)=1.5)
123+
</example>
109124
</description>
110125
</function>
111126
***/

‎funcs/func_rand.c

+3-2
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,9 @@
4949
<para>Choose a random number between <replaceable>min</replaceable> and <replaceable>max</replaceable>.
5050
<replaceable>min</replaceable> defaults to <literal>0</literal>, if not specified, while <replaceable>max</replaceable> defaults
5151
to <literal>RAND_MAX</literal> (2147483647 on many systems).</para>
52-
<para>Example: Set(junky=${RAND(1,8)});
53-
Sets junky to a random number between 1 and 8, inclusive.</para>
52+
<example title="Set random number between 1 and 8, inclusive">
53+
exten => s,1,Set(junky=${RAND(1,8)})
54+
</example>
5455
</description>
5556
</function>
5657
***/

‎funcs/func_sha1.c

+5-3
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,11 @@
4545
</syntax>
4646
<description>
4747
<para>Generate a SHA1 digest via the SHA1 algorythm.</para>
48-
<para>Example: Set(sha1hash=${SHA1(junky)})</para>
49-
<para>Sets the asterisk variable sha1hash to the string <literal>60fa5675b9303eb62f99a9cd47f9f5837d18f9a0</literal>
50-
which is known as his hash</para>
48+
<example title="Set sha1hash variable to SHA1 hash of junky">
49+
exten => s,1,Set(sha1hash=${SHA1(junky)})
50+
</example>
51+
<para>The example above sets the asterisk variable sha1hash to the string <literal>60fa5675b9303eb62f99a9cd47f9f5837d18f9a0</literal>
52+
which is known as its hash</para>
5153
</description>
5254
</function>
5355
***/

‎funcs/func_shell.c

+3-1
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,9 @@ static int shell_helper(struct ast_channel *chan, const char *cmd, char *data,
9191
</syntax>
9292
<description>
9393
<para>Collects the output generated by a command executed by the system shell</para>
94-
<para>Example: <literal>Set(foo=${SHELL(echo bar)})</literal></para>
94+
<example title="Shell example">
95+
exten => s,1,Set(foo=${SHELL(echo bar)})
96+
</example>
9597
<note>
9698
<para>The command supplied to this function will be executed by the
9799
system's shell, typically specified in the SHELL environment variable. There

0 commit comments

Comments
 (0)