xmldocs: Improve examples.

Use example tags instead of regular para tags
where possible.

ASTERISK-30090

Change-Id: Iada8bbfda08f30b118cedf2d040bbb21e4966ec5

apps/app_confbridge.c

@@ -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>
+			<example title="Example 1b">
-			<para>same => n,Set(CONFBRIDGE(user,announce_join_leave)=yes)</para>
+			same => n,Set(CONFBRIDGE(user,template)=default_user)
-			<para>same => n,Set(CONFBRIDGE(user,startmuted)=yes)</para>
+			same => n,Set(CONFBRIDGE(user,announce_join_leave)=yes)
-			<para>same => n,ConfBridge(1) </para>
+			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>
+			<example title="Example 2">
-			<para>same => n,Set(CONFBRIDGE(user,template)=my_user)</para>
+			exten => 1,1,Answer()
-			<para>same => n,Set(CONFBRIDGE(user,admin)=yes)</para>
+			same => n,Set(CONFBRIDGE(user,template)=my_user)
-			<para>same => n,Set(CONFBRIDGE(user,marked)=yes)</para>
+			same => n,Set(CONFBRIDGE(user,admin)=yes)
-			<para>same => n,ConfBridge(1)</para>
+			same => n,Set(CONFBRIDGE(user,marked)=yes)
+			same => n,ConfBridge(1)
+			</example>
 		</description>
 	</function>
 	<function name="CONFBRIDGE_INFO" language="en_US">

funcs/func_cdr.c

@@ -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">

funcs/func_dialgroup.c

@@ -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>
+			<example title="Add 2 endpoints to a dial group">
-			<para>exten => 1,1,Set(DIALGROUP(mygroup,add)=SIP/10)</para>
+			exten => 1,1,Set(DIALGROUP(mygroup,add)=SIP/10)
-			<para>exten => 1,n,Set(DIALGROUP(mygroup,add)=SIP/20)</para>
+			same => n,Set(DIALGROUP(mygroup,add)=SIP/20)
-			<para>exten => 1,n,Dial(${DIALGROUP(mygroup)})</para>
+			same => n,Dial(${DIALGROUP(mygroup)})
+			</example>
 		</description>
 	</function>
  ***/

funcs/func_env.c

@@ -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>
+			<example title="Reads the entire content of the file">
-			<para>    Set(foo=${FILE(/tmp/test.txt)})</para>
+			same => n,Set(foo=${FILE(/tmp/test.txt)})
-			<para>    ;reads from the 11th byte to the end of the file (i.e. skips the first 10).</para>
+			</example>
-			<para>    Set(foo=${FILE(/tmp/test.txt,10)})</para>
+			<example title="Reads from the 11th byte to the end of the file (i.e. skips the first 10)">
-			<para>    ;reads from the 11th to 20th byte in the file (i.e. skip the first 10, then read 10 bytes).</para>
+			same => n,Set(foo=${FILE(/tmp/test.txt,10)})
-			<para>    Set(foo=${FILE(/tmp/test.txt,10,10)})</para>
+			</example>
-			<para/>
+			<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>
+			<example title="Reads the 3rd line of the file">
-			<para>    Set(foo=${FILE(/tmp/test.txt,3,1,l)})</para>
+			same => n,Set(foo=${FILE(/tmp/test.txt,3,1,l)})
-			<para>    ; reads the 3rd and 4th lines of the file.</para>
+			</example>
-			<para>    Set(foo=${FILE(/tmp/test.txt,3,2,l)})</para>
+			<example title="Reads the 3rd and 4th lines of the file">
-			<para>    ; reads from the third line to the end of the file.</para>
+			same => n,Set(foo=${FILE(/tmp/test.txt,3,2,l)})
-			<para>    Set(foo=${FILE(/tmp/test.txt,3,,l)})</para>
+			</example>
-			<para>    ; reads the last three lines of the file.</para>
+			<example title="Reads from the third line to the end of the file">
-			<para>    Set(foo=${FILE(/tmp/test.txt,-3,,l)})</para>
+			same => n,Set(foo=${FILE(/tmp/test.txt,3,,l)})
-			<para>    ; reads the 3rd line of a DOS-formatted file.</para>
+			</example>
-			<para>    Set(foo=${FILE(/tmp/test.txt,3,1,l,d)})</para>
+			<example title="Reads the last three lines of the file">
-			<para/>
+			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>
+			<example title="Truncate the file and write bar">
-			<para>    Set(FILE(/tmp/test.txt)=bar)</para>
+			same => n,Set(FILE(/tmp/test.txt)=bar)
-			<para>    ; Append "bar"</para>
+			</example>
-			<para>    Set(FILE(/tmp/test.txt,,,a)=bar)</para>
+			<example title="Append bar">
-			<para>    ; Replace the first byte with "bar" (replaces 1 character with 3)</para>
+			same => n,Set(FILE(/tmp/test.txt,,,a)=bar)
-			<para>    Set(FILE(/tmp/test.txt,0,1)=bar)</para>
+			</example>
-			<para>    ; Replace 10 bytes beginning at the 21st byte of the file with "bar"</para>
+			<example title="Replace the first byte with bar (replaces 1 character with 3)">
-			<para>    Set(FILE(/tmp/test.txt,20,10)=bar)</para>
+			same => n,Set(FILE(/tmp/test.txt,0,1)=bar)
-			<para>    ; Replace all bytes from the 21st with "bar"</para>
+			</example>
-			<para>    Set(FILE(/tmp/test.txt,20)=bar)</para>
+			<example title="Replace 10 bytes beginning at the 21st byte of the file with bar">
-			<para>    ; Insert "bar" after the 4th character</para>
+			same => n,Set(FILE(/tmp/test.txt,20,10)=bar)
-			<para>    Set(FILE(/tmp/test.txt,4,0)=bar)</para>
+			</example>
-			<para/>
+			<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>
+			<example title="Replace the first line of the file with bar">
-			<para>    Set(FILE(/tmp/foo.txt,0,1,l)=bar)</para>
+			same => n,Set(FILE(/tmp/foo.txt,0,1,l)=bar)
-			<para>    ; Replace the last line of the file with "bar"</para>
+			</example>
-			<para>    Set(FILE(/tmp/foo.txt,-1,,l)=bar)</para>
+			<example title="Replace the last line of the file with bar">
-			<para>    ; Append "bar" to the file with a newline</para>
+			same => n,Set(FILE(/tmp/foo.txt,-1,,l)=bar)
-			<para>    Set(FILE(/tmp/foo.txt,,,al)=bar)</para>
+			</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

funcs/func_frame_drop.c

@@ -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>
+			<example title="Drop only DTMF frames towards this channel">
-			<para>exten => 1,1,Set(FRAME_DROP(TX)=ANSWER); drop only ANSWER CONTROL frames towards this channel.</para>
+			exten => 1,1,Set(FRAME_DROP(TX)=DTMF_BEGIN,DTMF_END)
-			<para>exten => 1,1,Set(FRAME_DROP(RX)=DTMF_BEGIN,DTMF_END); drop only DTMF frames received on this channel.</para>
+			</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>
  ***/

funcs/func_frame_trace.c

@@ -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>
+			<example title="View only DTMF frames">
-			<para>exten => 1,1,Set(FRAME_TRACE()=DTMF_BEGIN,DTMF_END); view only DTMF frames. </para>
+			exten => 1,1,Set(FRAME_TRACE(white)=DTMF_BEGIN,DTMF_END)
-			<para>exten => 1,1,Set(FRAME_TRACE(black)=DTMF_BEGIN,DTMF_END); view everything except DTMF frames. </para>
+			</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>
  ***/

funcs/func_math.c

@@ -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">
@@ -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>
+			<example title="Decrements MyVAR">
-			<para>Note: DEC(${MyVAR}) - Is wrong, as DEC expects the variable name, not its value</para>
+			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">
@@ -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)});
+			<example title="Sets the min variable equal to 4">
-			Sets the min variable equal to 4.</para>
+			same => n,Set(min=${MIN(7,4)})
+			</example>
 		</description>
 	</function>
 	<function name="MAX" language="en_US">
@@ -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)});
+			<example title="Sets the max variable equal to 13">
-			Sets the max variable equal to 7.</para>
+			same => n,Set(max=${MAX(4,7)})
+			</example>
 		</description>
 	</function>
 	<function name="ABS" language="en_US">
@@ -160,8 +166,9 @@
 		</syntax>
 		<description>
 			<para>Returns the absolute value of a number <replaceable>num</replaceable>.</para>
-			<para>Example:  Set(absval=${ABS(-13)});
+			<example title="Sets the absval variable equal to 13">
-			Sets the absval variable equal to 13.</para>
+			same => n,Set(absval=${ABS(-13)})
+			</example>
 		</description>
 	</function>
  ***/

funcs/func_odbc.c

@@ -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">
@@ -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>
  ***/

funcs/func_periodic_hook.c

@@ -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>
+			<example title="To turn on">
-			<para>  Set(BEEPID=${PERIODIC_HOOK(hooks,beep,180)})</para>
+			same => n,Set(BEEPID=${PERIODIC_HOOK(hooks,beep,180)})
-			<para/>
+			</example>
-			<para>To turn off:</para>
+			<example title="To turn off">
-			<para>  Set(PERIODIC_HOOK(${BEEPID})=off)</para>
+			same => n,Set(PERIODIC_HOOK(${BEEPID})=off)
-			<para/>
+			</example>
-			<para>To turn back on again later:</para>
+			<example title="To turn back on again later">
-			<para>Set(PERIODIC_HOOK(${BEEPID})=on)</para>
+			same => n,Set(PERIODIC_HOOK(${BEEPID})=on)
-			<para/>
+			</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

funcs/func_pitchshift.c

@@ -97,15 +97,30 @@
 		</syntax>
 		<description>
 			<para>Examples:</para>
-			<para>exten => 1,1,Set(PITCH_SHIFT(tx)=highest); raises pitch an octave </para>
+			<example title="Raises pitch an octave">
-			<para>exten => 1,1,Set(PITCH_SHIFT(rx)=higher) ; raises pitch more </para>
+			exten => 1,1,Set(PITCH_SHIFT(tx)=highest)
-			<para>exten => 1,1,Set(PITCH_SHIFT(both)=high)   ; raises pitch </para>
+			</example>
-			<para>exten => 1,1,Set(PITCH_SHIFT(rx)=low)    ; lowers pitch </para>
+			<example title="Raises pitch more">
-			<para>exten => 1,1,Set(PITCH_SHIFT(tx)=lower)  ; lowers pitch more </para>
+			exten => 1,1,Set(PITCH_SHIFT(rx)=higher)
-			<para>exten => 1,1,Set(PITCH_SHIFT(both)=lowest) ; lowers pitch an octave </para>
+			</example>
-
+			<example title="Raises pitch">
-			<para>exten => 1,1,Set(PITCH_SHIFT(rx)=0.8)    ; lowers pitch </para>
+			exten => 1,1,Set(PITCH_SHIFT(both)=high)
-			<para>exten => 1,1,Set(PITCH_SHIFT(tx)=1.5)    ; raises pitch </para>
+			</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>
  ***/

funcs/func_rand.c

@@ -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)});
+			<example title="Set random number between 1 and 8, inclusive">
-			Sets junky to a random number between 1 and 8, inclusive.</para>
+			exten => s,1,Set(junky=${RAND(1,8)})
+			</example>
 		</description>
 	</function>
  ***/

funcs/func_sha1.c

@@ -45,9 +45,11 @@
 		</syntax>
 		<description>
 			<para>Generate a SHA1 digest via the SHA1 algorythm.</para>
-			<para>Example:  Set(sha1hash=${SHA1(junky)})</para>
+			<example title="Set sha1hash variable to SHA1 hash of junky">
-			<para>Sets the asterisk variable sha1hash to the string <literal>60fa5675b9303eb62f99a9cd47f9f5837d18f9a0</literal>
+			exten => s,1,Set(sha1hash=${SHA1(junky)})
-			which is known as his hash</para>
+			</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>
  ***/

funcs/func_shell.c

@@ -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

funcs/func_speex.c

@@ -66,9 +66,10 @@
 			analog lines, but could be useful for other channels as well. The target volume
 			is set with a number between <literal>1-32768</literal>. The larger the number
 			the louder (more gain) the channel will receive.</para>
-			<para>Examples:</para>
+			<example title="Apply automatic gain control">
-			<para>exten => 1,1,Set(AGC(rx)=8000)</para>
+			exten => 1,1,Set(AGC(rx)=8000)
-			<para>exten => 1,2,Set(AGC(tx)=off)</para>
+			exten => 1,2,Set(AGC(tx)=off)
+			</example>
 		</description>
 	</function>
 	<function name="DENOISE" language="en_US">
@@ -87,9 +88,10 @@
 			that it is executed on. It is very useful for noisy analog lines, especially
 			when adjusting gains or using AGC. Use <literal>rx</literal> for audio received from the channel
 			and <literal>tx</literal> to apply the filter to the audio being sent to the channel.</para>
-			<para>Examples:</para>
+			<example title="Apply noise reduction">
-			<para>exten => 1,1,Set(DENOISE(rx)=on)</para>
+			exten => 1,1,Set(DENOISE(rx)=on)
-			<para>exten => 1,2,Set(DENOISE(tx)=off)</para>
+			exten => 1,2,Set(DENOISE(tx)=off)
+			</example>
 		</description>
 	</function>
  ***/

funcs/func_strings.c

@@ -62,7 +62,10 @@ AST_THREADSTORAGE(tmp_buf);
 			carriage return, and tab characters, respectively.  Also, octal and hexadecimal specifications are recognized
 			by the patterns <literal>\0nnn</literal> and <literal>\xHH</literal>, respectively.  For example, if you wanted
 			to encode a comma as the delimiter, you could use either <literal>\054</literal> or <literal>\x2C</literal>.</para>
-			<para>Example: If ${example} contains <literal>ex-amp-le</literal>, then ${FIELDQTY(example,-)} returns 3.</para>
+			<example title="Prints 3">
+			exten => s,1,Set(example=ex-amp-le)
+				same => n,NoOp(${FIELDQTY(example,-)})
+			</example>
 		</description>
 	</function>
 	<function name="FIELDNUM" language="en_US">
@@ -83,7 +86,10 @@ AST_THREADSTORAGE(tmp_buf);
 			carriage return, and tab characters, respectively.  Also, octal and hexadecimal specifications are recognized
 			by the patterns <literal>\0nnn</literal> and <literal>\xHH</literal>, respectively.  For example, if you wanted
 			to encode a comma as the delimiter, you could use either <literal>\054</literal> or <literal>\x2C</literal>.</para>
-		        <para>Example: If ${example} contains <literal>ex-amp-le</literal>, then ${FIELDNUM(example,-,amp)} returns 2.</para>
+			<example title="Prints 2">
+			exten => s,1,Set(example=ex-amp-le)
+				same => n,NoOp(${FIELDNUM(example,-,amp)})
+			</example>
 		</description>
 	</function>
 	<function name="LISTFILTER" language="en_US">
@@ -190,8 +196,10 @@ AST_THREADSTORAGE(tmp_buf);
 			string, instead.</para>
 			<note><para>The functions which take a variable name need to be passed var and not
 			${var}.  Similarly, use PASSTHRU() and not ${PASSTHRU()}.</para></note>
-			<para>Example: ${CHANNEL} contains SIP/321-1</para>
+			<example title="Prints 321">
-			<para>         ${CUT(PASSTHRU(${CUT(CHANNEL,-,1)}),/,2)}) will return 321</para>
+			exten => s,1,NoOp(${CHANNEL}) ; contains SIP/321-1
+				same => n,NoOp(${CUT(PASSTHRU(${CUT(CHANNEL,-,1)}),/,2)})
+			</example>
 		</description>
 	</function>
 	<function name="REGEX" language="en_US">
@@ -257,7 +265,9 @@ AST_THREADSTORAGE(tmp_buf);
 			<parameter name="string" required="true" />
 		</syntax>
 		<description>
-			<para>Example: ${KEYPADHASH(Les)} returns "537"</para>
+			<example title="Returns 537">
+			exten => s,1,Return(${KEYPADHASH(Les)})
+			</example>
 		</description>
 	</function>
 	<function name="ARRAY" language="en_US">
@@ -273,7 +283,9 @@ AST_THREADSTORAGE(tmp_buf);
 			<para>The comma-delimited list passed as a value to which the function is set will
 			be interpreted as a set of values to which the comma-delimited list of
 			variable names in the argument should be set.</para>
-			<para>Example: Set(ARRAY(var1,var2)=1,2) will set var1 to 1 and var2 to 2</para>
+			<example title="Set var1 to 1 and var2 to 2">
+			same => n,Set(ARRAY(var1,var2)=1,2)
+			</example>
 		</description>
 	</function>
 	<function name="STRPTIME" language="en_US">
@@ -289,7 +301,9 @@ AST_THREADSTORAGE(tmp_buf);
 			<para>This is useful for converting a date into <literal>EPOCH</literal> time,
 			possibly to pass to an application like SayUnixTime or to calculate the difference
 			between the two date strings</para>
-			<para>Example: ${STRPTIME(2006-03-01 07:30:35,America/Chicago,%Y-%m-%d %H:%M:%S)} returns 1141219835</para>
+			<example title="Prints 1141219835">
+			same => n,NoOp(${STRPTIME(2006-03-01 07:30:35,America/Chicago,%Y-%m-%d %H:%M:%S)})
+			</example>
 		</description>
 	</function>
 	<function name="STRFTIME" language="en_US">
@@ -343,7 +357,9 @@ AST_THREADSTORAGE(tmp_buf);
 			<parameter name="string" required="true" />
 		</syntax>
 		<description>
-			<para>Example: ${TOUPPER(Example)} returns "EXAMPLE"</para>
+			<example title="Prints EXAMPLE">
+			exten => s,1,NoOp(${TOUPPER(Example)})
+			</example>
 		</description>
 	</function>
 	<function name="TOLOWER" language="en_US">
@@ -354,7 +370,9 @@ AST_THREADSTORAGE(tmp_buf);
 			<parameter name="string" required="true" />
 		</syntax>
 		<description>
-			<para>Example: ${TOLOWER(Example)} returns "example"</para>
+			<example title="Prints example">
+			exten => s,1,NoOp(${TOLOWER(Example)})
+			</example>
 		</description>
 	</function>
 	<function name="LEN" language="en_US">
@@ -365,7 +383,9 @@ AST_THREADSTORAGE(tmp_buf);
 			<parameter name="string" required="true" />
 		</syntax>
 		<description>
-			<para>Example: ${LEN(example)} returns 7</para>
+			<example title="Prints 7">
+			exten => s,1,NoOp(${LEN(example)})
+			</example>
 		</description>
 	</function>
 	<function name="QUOTE" language="en_US">
@@ -399,11 +419,12 @@ AST_THREADSTORAGE(tmp_buf);
 			<parameter name="delimiter" required="false" default="," />
 		</syntax>
 		<description>
-			<para>Example:</para>
+			<example title="SHIFT example">
-			<para>exten => s,1,Set(array=one,two,three)</para>
+			exten => s,1,Set(array=one,two,three)
-			<para>exten => s,n,While($["${SET(var=${SHIFT(array)})}" != ""])</para>
+			exten => s,n,While($["${SET(var=${SHIFT(array)})}" != ""])
-			<para>exten => s,n,NoOp(var is ${var})</para>
+			exten => s,n,NoOp(var is ${var})
-			<para>exten => s,n,EndWhile</para>
+			exten => s,n,EndWhile
+			</example>
 			<para>This would iterate over each value in array, left to right, and
 				would result in NoOp(var is one), NoOp(var is two), and
 				NoOp(var is three) being executed.
@@ -419,11 +440,12 @@ AST_THREADSTORAGE(tmp_buf);
 			<parameter name="delimiter" required="false" default="," />
 		</syntax>
 		<description>
-			<para>Example:</para>
+			<example title="POP example">
-			<para>exten => s,1,Set(array=one,two,three)</para>
+			exten => s,1,Set(array=one,two,three)
-			<para>exten => s,n,While($["${SET(var=${POP(array)})}" != ""])</para>
+			exten => s,n,While($["${SET(var=${POP(array)})}" != ""])
-			<para>exten => s,n,NoOp(var is ${var})</para>
+			exten => s,n,NoOp(var is ${var})
-			<para>exten => s,n,EndWhile</para>
+			exten => s,n,EndWhile
+			</example>
 			<para>This would iterate over each value in array, right to left, and
 				would result in NoOp(var is three), NoOp(var is two), and
 				NoOp(var is one) being executed.
@@ -439,7 +461,10 @@ AST_THREADSTORAGE(tmp_buf);
 			<parameter name="delimiter" required="false" default="," />
 		</syntax>
 		<description>
-			<para>Example: Set(PUSH(array)=one,two,three) would append one,
+			<example title="PUSH example">
+			exten => s,1,Set(PUSH(array)=one,two,three)
+			</example>
+			<para>This would append one,
 				two, and three to the end of the values stored in the variable
 				"array".
 			</para>
@@ -454,7 +479,10 @@ AST_THREADSTORAGE(tmp_buf);
 			<parameter name="delimiter" required="false" default="," />
 		</syntax>
 		<description>
-			<para>Example: Set(UNSHIFT(array)=one,two,three) would insert one,
+			<example title="UNSHIFT example">
+			exten => s,1,Set(UNSHIFT(array)=one,two,three)
+			</example>
+			<para>This would insert one,
 				two, and three before the values stored in the variable
 				"array".
 			</para>

funcs/func_talkdetect.c

@@ -103,11 +103,18 @@
 			natural speech.</para>
 			<para>By default this value is 2500ms. Valid values are 1
 			through 2^31.</para>
-			<para>Example:</para>
+			<example title="Enable talk detection">
-			<para>same => n,Set(TALK_DETECT(set)=)     ; Enable talk detection</para>
+			same => n,Set(TALK_DETECT(set)=)
-			<para>same => n,Set(TALK_DETECT(set)=1200) ; Update existing talk detection's silence threshold to 1200 ms</para>
+			</example>
-			<para>same => n,Set(TALK_DETECT(remove)=)  ; Remove talk detection</para>
+			<example title="Update existing talk detection's silence threshold to 1200 ms">
-			<para>same => n,Set(TALK_DETECT(set)=,128) ; Enable and set talk threshold to 128</para>
+			same => n,Set(TALK_DETECT(set)=1200)
+			</example>
+			<example title="Remove talk detection">
+			same => n,Set(TALK_DETECT(remove)=)
+			</example>
+			<example title="Enable and set talk threshold to 128">
+			same => n,Set(TALK_DETECT(set)=,128)
+			</example>
 			<para>This function will set the following variables:</para>
 			<note>
 				<para>The TALK_DETECT function uses an audiohook to inspect the
@@ -117,10 +124,11 @@
 				it typically makes sense to place functions that modify the voice
 				media data prior to placing the TALK_DETECT function, as this will
 				yield better results.</para>
-				<para>Example:</para>
-				<para>same => n,Set(DENOISE(rx)=on)    ; Denoise received audio</para>
-				<para>same => n,Set(TALK_DETECT(set)=) ; Perform talk detection on the denoised received audio</para>
 			</note>
+			<example title="Denoise and then perform talk detection">
+			same => n,Set(DENOISE(rx)=on)    ; Denoise received audio
+			same => n,Set(TALK_DETECT(set)=) ; Perform talk detection on the denoised received audio
+			</example>
 		</description>
 	</function>
  ***/

funcs/func_version.c

@@ -47,7 +47,7 @@
 				<enumlist>
 					<enum name="ASTERISK_VERSION_NUM">
 						<para>A string of digits is returned, e.g. 10602 for 1.6.2 or 100300 for 10.3.0,
-						or 999999 when using an SVN build.</para>
+						or 999999 when using a Git build.</para>
 					</enum>
 					<enum name="BUILD_USER">
 						<para>The string representing the user's name whose account
@@ -73,9 +73,10 @@
 			</parameter>
 		</syntax>
 		<description>
-			<para>If there are no arguments, return the version of Asterisk in this format: SVN-branch-1.4-r44830M</para>
+			<para>If there are no arguments, return the version of Asterisk in this format: 18.12.0</para>
-			<para>Example:  Set(junky=${VERSION()};</para>
+			<example title="Get current version">
-			<para>Sets junky to the string <literal>SVN-branch-1.6-r74830M</literal>, or possibly, <literal>SVN-trunk-r45126M</literal>.</para>
+			same => n,Set(junky=${VERSION()} ; sets junky to 18.12.0, or possibly GITMasterxxxxxx
+			</example>
 		</description>
 	</function>
  ***/

funcs/func_vmcount.c

@@ -57,7 +57,9 @@
 		<description>
 			<para>Count the number of voicemails in a specified mailbox, you could also specify
 			the mailbox <replaceable>folder</replaceable>.</para>
-			<para>Example: <literal>exten => s,1,Set(foo=${VMCOUNT(125@default)})</literal></para>
+			<example title="Mailbox folder count">
+			exten => s,1,Set(foo=${VMCOUNT(125@default)})
+			</example>
 			<para>An ampersand-separated list of mailboxes may be specified to count voicemails in
 			multiple mailboxes. If a folder is specified, this will apply to all mailboxes specified.</para>
                         <example title="Multiple mailbox inbox count">

funcs/func_volume.c

@@ -59,11 +59,24 @@
 		<description>
 			<para>The VOLUME function can be used to increase or decrease the <literal>tx</literal> or
 			<literal>rx</literal> gain of any channel.</para>
-			<para>For example:</para>
+			<example title="Increase volume">
-			<para>Set(VOLUME(TX)=3)</para>
+			same => n,Set(VOLUME(TX)=3)
-			<para>Set(VOLUME(RX)=2)</para>
+			</example>
-			<para>Set(VOLUME(TX,p)=3)</para>
+			<example title="Increase volume">
-			<para>Set(VOLUME(RX,p)=3)</para>
+			same => n,Set(VOLUME(RX)=2)
+			</example>
+			<example title="Increase volume with DTMF control">
+			same => n,Set(VOLUME(TX,p)=3)
+			</example>
+			<example title="Increase RX volume with DTMF control">
+			same => n,Set(VOLUME(RX,p)=3)
+			</example>
+			<example title="Decrease RX volume">
+			same => n,Set(VOLUME(RX)=-4)
+			</example>
+			<example title="Reset to normal">
+			same => n,Set(VOLUME(RX)=0)
+			</example>
 		</description>
 	</function>
  ***/

res/res_calendar.c

@@ -193,7 +193,9 @@
 			</parameter>
 		</syntax>
 		<description>
-			<para>Example: CALENDAR_WRITE(calendar,field1,field2,field3)=val1,val2,val3</para>
+			<example title="Set calendar fields">
+			same => n,Set(CALENDAR_WRITE(calendar,field1,field2,field3)=val1,val2,val3)
+			</example>
 			<para>The field and value arguments can easily be set/passed using the HASHKEYS() and HASH() functions</para>
 			<variablelist>
 				<variable name="CALENDAR_SUCCESS">

res/res_mutestream.c

@@ -69,16 +69,13 @@
 			</parameter>
 		</syntax>
 		<description>
-			<para>The MUTEAUDIO function can be used to mute inbound (to the PBX) or outbound audio in a call.
+			<para>The MUTEAUDIO function can be used to mute inbound (to the PBX) or outbound audio in a call.</para>
-			</para>
+			<example title="Mute incoming audio">
-			<para>Examples:
+			exten => s,1,Set(MUTEAUDIO(in)=on)
-			</para>
+			</example>
-			<para>
+			<example title="Do not mute incoming audio">
-			MUTEAUDIO(in)=on
+			exten => s,1,Set(MUTEAUDIO(in)=off)
-			</para>
+			</example>
-			<para>
-			MUTEAUDIO(in)=off
-			</para>
 		</description>
 	</function>
 	<manager name="MuteAudio" language="en_US">

res/res_pjsip_config_wizard.c

@@ -65,25 +65,24 @@
 			endpoint, aor, contact, auth and phoneprov objects necessary for a phone to
 			get phone provisioning information, register, and make and receive calls.
 			A hint is also created in the default context for extension 1000.</para>
-			<para> </para>
+			<example title="myphone">
-
+			[myphone]
-			<para>[myphone]</para>
+			type = wizard
-			<para>type = wizard</para>
+			sends_auth = no
-			<para>sends_auth = no</para>
+			accepts_auth = yes
-			<para>accepts_auth = yes</para>
+			sends_registrations = no
-			<para>sends_registrations = no</para>
+			accepts_registrations = yes
-			<para>accepts_registrations = yes</para>
+			has_phoneprov = yes
-			<para>has_phoneprov = yes</para>
+			transport = ipv4
-			<para>transport = ipv4</para>
+			has_hint = yes
-			<para>has_hint = yes</para>
+			hint_exten = 1000
-			<para>hint_exten = 1000</para>
+			inbound_auth/username = testname
-			<para>inbound_auth/username = testname</para>
+			inbound_auth/password = test password
-			<para>inbound_auth/password = test password</para>
+			endpoint/allow = ulaw
-			<para>endpoint/allow = ulaw</para>
+			endpoint/context = default
-			<para>endpoint/context = default</para>
+			phoneprov/MAC = 001122aa4455
-			<para>phoneprov/MAC = 001122aa4455</para>
+			phoneprov/PROFILE = profile1
-			<para>phoneprov/PROFILE = profile1</para>
+			</example>
-			<para> </para>
 
 			<para>The first 8 items are specific to the wizard.  The rest of the items
 			are passed verbatim to the underlying objects.</para>
@@ -92,21 +91,20 @@
 			<para>The following configuration snippet would create the
 			endpoint, aor, contact, auth, identify and registration objects necessary for a trunk
 			to another pbx or ITSP that requires registration.</para>
-			<para> </para>
+			<example title="mytrunk">
-
+			[mytrunk]
-			<para>[mytrunk]</para>
+			type = wizard
-			<para>type = wizard</para>
+			sends_auth = yes
-			<para>sends_auth = yes</para>
+			accepts_auth = no
-			<para>accepts_auth = no</para>
+			sends_registrations = yes
-			<para>sends_registrations = yes</para>
+			accepts_registrations = no
-			<para>accepts_registrations = no</para>
+			transport = ipv4
-			<para>transport = ipv4</para>
+			remote_hosts = sip1.myitsp.com:5060,sip2.myitsp.com:5060
-			<para>remote_hosts = sip1.myitsp.com:5060,sip2.myitsp.com:5060</para>
+			outbound_auth/username = testname
-			<para>outbound_auth/username = testname</para>
+			outbound_auth/password = test password
-			<para>outbound_auth/password = test password</para>
+			endpoint/allow = ulaw
-			<para>endpoint/allow = ulaw</para>
+			endpoint/context = default
-			<para>endpoint/context = default</para>
+			</example>
-			<para> </para>
 
 			<para>Of course, any of the items in either example could be placed into
 			templates and shared among wizard objects.</para>
@@ -227,10 +225,10 @@
 					<para>   <literal>exten =&gt; &lt;hint_exten&gt;,1,&lt;hint_application&gt;</literal></para>
 					<para> </para>
 					<para>You can specify any valid extensions.conf application expression.</para>
-					<para>Examples: </para>
+					<example title="Valid expressions">
-					<para>   <literal>Dial(${HINT})</literal></para>
+					Dial(${HINT})
-					<para>   <literal>Gosub(stdexten,${EXTEN},1(${HINT}))</literal></para>
+					Gosub(stdexten,${EXTEN},1(${HINT}))
-					<para> </para>
+					</example>
 					<para>Any extensions.conf style variables specified are passed directly to the
 					dialplan.</para>
 					<para> </para>

res/res_pjsip_header_funcs.c

@@ -84,65 +84,59 @@
 			channel. One exception is that you can read headers that you have already
 			added on the outbound channel.</para>
 			<para>Examples:</para>
-			<para>;</para>
+			<example title="Set somevar to the value of the From header">
-			<para>; Set 'somevar' to the value of the 'From' header.</para>
+			exten => 1,1,Set(somevar=${PJSIP_HEADER(read,From)})
-			<para>exten => 1,1,Set(somevar=${PJSIP_HEADER(read,From)})</para>
+			</example>
-			<para>;</para>
+			<example title="Set via2 to the value of the 2nd Via header">
-			<para>; Set 'via2' to the value of the 2nd 'Via' header.</para>
+			exten => 1,1,Set(via2=${PJSIP_HEADER(read,Via,2)})
-			<para>exten => 1,1,Set(via2=${PJSIP_HEADER(read,Via,2)})</para>
+			</example>
-			<para>;</para>
+			<example title="Set xhdr to the value of the 1st X-header">
-			<para>; Set 'xhdr' to the value of the 1sx X-header.</para>
+			exten => 1,1,Set(xhdr=${PJSIP_HEADER(read,X-*,1)})
-			<para>exten => 1,1,Set(xhdr=${PJSIP_HEADER(read,X-*,1)})</para>
+			</example>
-			<para>;</para>
+			<example title="Add an X-Myheader header with the value of myvalue">
-			<para>; Add an 'X-Myheader' header with the value of 'myvalue'.</para>
+			exten => 1,1,Set(PJSIP_HEADER(add,X-MyHeader)=myvalue)
-			<para>exten => 1,1,Set(PJSIP_HEADER(add,X-MyHeader)=myvalue)</para>
+			</example>
-			<para>;</para>
+			<example title="Add an X-Myheader header with an empty value">
-			<para>; Add an 'X-Myheader' header with an empty value.</para>
+			exten => 1,1,Set(PJSIP_HEADER(add,X-MyHeader)=)
-			<para>exten => 1,1,Set(PJSIP_HEADER(add,X-MyHeader)=)</para>
+			</example>
-			<para>;</para>
+			<example title="Update the value of the header named X-Myheader to newvalue">
-			<para>; Update the value of the header named 'X-Myheader' to 'newvalue'.</para>
+			; 'X-Myheader' must already exist or the call will fail.
-			<para>; 'X-Myheader' must already exist or the call will fail.</para>
+			exten => 1,1,Set(PJSIP_HEADER(update,X-MyHeader)=newvalue)
-			<para>exten => 1,1,Set(PJSIP_HEADER(update,X-MyHeader)=newvalue)</para>
+			</example>
-			<para>;</para>
+			<example title="Remove all headers whose names exactly match X-MyHeader">
-			<para>; Remove all headers whose names exactly match 'X-MyHeader'.</para>
+			exten => 1,1,Set(PJSIP_HEADER(remove,X-MyHeader)=)
-			<para>exten => 1,1,Set(PJSIP_HEADER(remove,X-MyHeader)=)</para>
+			</example>
-			<para>;</para>
+			<example title="Remove all headers that begin with X-My">
-			<para>; Remove all headers that begin with 'X-My'.</para>
+			exten => 1,1,Set(PJSIP_HEADER(remove,X-My*)=)
-			<para>exten => 1,1,Set(PJSIP_HEADER(remove,X-My*)=)</para>
+			</example>
-			<para>;</para>
+			<example title="Remove all previously added headers">
-			<para>; Remove all previously added headers.</para>
+			exten => 1,1,Set(PJSIP_HEADER(remove,*)=)
-			<para>exten => 1,1,Set(PJSIP_HEADER(remove,*)=)</para>
+			</example>
-			<para>;</para>
-
 			<note><para>The <literal>remove</literal> action can be called by reading
-			<emphasis>or</emphasis> writing PJSIP_HEADER.</para>
+			<emphasis>or</emphasis> writing PJSIP_HEADER.</para></note>
-			<para>;</para>
+			<example title="Display the number of headers removed">
-			<para>; Display the number of headers removed</para>
+			exten => 1,1,Verbose( Removed ${PJSIP_HEADER(remove,X-MyHeader)} headers)
-			<para>exten => 1,1,Verbose( Removed ${PJSIP_HEADER(remove,X-MyHeader)} headers)</para>
+			</example>
-			<para>;</para>
+			<example title="Set a variable to the number of headers removed">
-			<para>; Set a variable to the number of headers removed</para>
+			exten => 1,1,Set(count=${PJSIP_HEADER(remove,X-MyHeader)})
-			<para>exten => 1,1,Set(count=${PJSIP_HEADER(remove,X-MyHeader)})</para>
+			</example>
-			<para>;</para>
+			<example title="Just remove them ignoring any count">
-			<para>; Just remove them ignoring any count</para>
+			exten => 1,1,Set(=${PJSIP_HEADER(remove,X-MyHeader)})
-			<para>exten => 1,1,Set(=${PJSIP_HEADER(remove,X-MyHeader)})</para>
+			exten => 1,1,Set(PJSIP_HEADER(remove,X-MyHeader)=)
-			<para>exten => 1,1,Set(PJSIP_HEADER(remove,X-MyHeader)=)</para>
+			</example>
-			<para>;</para>
-			</note>
 
 			<note><para>If you call PJSIP_HEADER in a normal dialplan context you'll be
 			operating on the <emphasis>caller's (incoming)</emphasis> channel which
 			may not be what you want. To operate on the <emphasis>callee's (outgoing)</emphasis>
-			channel call PJSIP_HEADER in a pre-dial handler. </para>
+			channel call PJSIP_HEADER in a pre-dial handler. </para></note>
-			<para>Example:</para>
+			<example title="Set headers on callee channel">
-			<para>;</para>
+			[handler]
-			<para>[handler]</para>
+			exten => addheader,1,Set(PJSIP_HEADER(add,X-MyHeader)=myvalue)
-			<para>exten => addheader,1,Set(PJSIP_HEADER(add,X-MyHeader)=myvalue)</para>
+			exten => addheader,2,Set(PJSIP_HEADER(add,X-MyHeader2)=myvalue2)
-			<para>exten => addheader,2,Set(PJSIP_HEADER(add,X-MyHeader2)=myvalue2)</para>
+
-			<para>;</para>
+			[somecontext]
-			<para>[somecontext]</para>
+			exten => 1,1,Dial(PJSIP/${EXTEN},,b(handler^addheader^1))
-			<para>exten => 1,1,Dial(PJSIP/${EXTEN},,b(handler^addheader^1))</para>
+			</example>
-			<para>;</para>
-			</note>
 		</description>
 	</function>
 	<function name="PJSIP_HEADERS" language="en_US">