kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-11-03 12:25:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

xmldocs: Improve examples.

Browse Source 
Use example tags instead of regular para tags
where possible.

ASTERISK-30090

Change-Id: Iada8bbfda08f30b118cedf2d040bbb21e4966ec5
This commit is contained in:
Naveen Albert
2022-06-01 01:43:52 +00:00
committed by Friendly Automation
parent e92f047e5f
commit 7f892d03a5
23 changed files with 353 additions and 243 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
res/res_calendar.c
View File

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

17
res/res_mutestream.c
View File

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

74
res/res_pjsip_config_wizard.c
View File

@@ -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>
<para>[myphone]</para>
<para>type = wizard</para>
<para>sends_auth = no</para>
<para>accepts_auth = yes</para>
<para>sends_registrations = no</para>
<para>accepts_registrations = yes</para>
<para>has_phoneprov = yes</para>
<para>transport = ipv4</para>
<para>has_hint = yes</para>
<para>hint_exten = 1000</para>
<para>inbound_auth/username = testname</para>
<para>inbound_auth/password = test password</para>
<para>endpoint/allow = ulaw</para>
<para>endpoint/context = default</para>
<para>phoneprov/MAC = 001122aa4455</para>
<para>phoneprov/PROFILE = profile1</para>
<para> </para>
<example title="myphone">
[myphone]
type = wizard
sends_auth = no
accepts_auth = yes
sends_registrations = no
accepts_registrations = yes
has_phoneprov = yes
transport = ipv4
has_hint = yes
hint_exten = 1000
inbound_auth/username = testname
inbound_auth/password = test password
endpoint/allow = ulaw
endpoint/context = default
phoneprov/MAC = 001122aa4455
phoneprov/PROFILE = profile1
</example>
<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>
<para>[mytrunk]</para>
<para>type = wizard</para>
<para>sends_auth = yes</para>
<para>accepts_auth = no</para>
<para>sends_registrations = yes</para>
<para>accepts_registrations = no</para>
<para>transport = ipv4</para>
<para>remote_hosts = sip1.myitsp.com:5060,sip2.myitsp.com:5060</para>
<para>outbound_auth/username = testname</para>
<para>outbound_auth/password = test password</para>
<para>endpoint/allow = ulaw</para>
<para>endpoint/context = default</para>
<para> </para>
<example title="mytrunk">
[mytrunk]
type = wizard
sends_auth = yes
accepts_auth = no
sends_registrations = yes
accepts_registrations = no
transport = ipv4
remote_hosts = sip1.myitsp.com:5060,sip2.myitsp.com:5060
outbound_auth/username = testname
outbound_auth/password = test password
endpoint/allow = ulaw
endpoint/context = default
</example>
<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>
<para> <literal>Dial(${HINT})</literal></para>
<para> <literal>Gosub(stdexten,${EXTEN},1(${HINT}))</literal></para>
<para> </para>
<example title="Valid expressions">
Dial(${HINT})
Gosub(stdexten,${EXTEN},1(${HINT}))
</example>
<para>Any extensions.conf style variables specified are passed directly to the
dialplan.</para>
<para> </para>

102
res/res_pjsip_header_funcs.c
View File

@@ -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>
<para>; Set 'somevar' to the value of the 'From' header.</para>
<para>exten => 1,1,Set(somevar=${PJSIP_HEADER(read,From)})</para>
<para>;</para>
<para>; Set 'via2' to the value of the 2nd 'Via' header.</para>
<para>exten => 1,1,Set(via2=${PJSIP_HEADER(read,Via,2)})</para>
<para>;</para>
<para>; Set 'xhdr' to the value of the 1sx X-header.</para>
<para>exten => 1,1,Set(xhdr=${PJSIP_HEADER(read,X-*,1)})</para>
<para>;</para>
<para>; Add an 'X-Myheader' header with the value of 'myvalue'.</para>
<para>exten => 1,1,Set(PJSIP_HEADER(add,X-MyHeader)=myvalue)</para>
<para>;</para>
<para>; Add an 'X-Myheader' header with an empty value.</para>
<para>exten => 1,1,Set(PJSIP_HEADER(add,X-MyHeader)=)</para>
<para>;</para>
<para>; Update the value of the header named 'X-Myheader' to 'newvalue'.</para>
<para>; 'X-Myheader' must already exist or the call will fail.</para>
<para>exten => 1,1,Set(PJSIP_HEADER(update,X-MyHeader)=newvalue)</para>
<para>;</para>
<para>; Remove all headers whose names exactly match 'X-MyHeader'.</para>
<para>exten => 1,1,Set(PJSIP_HEADER(remove,X-MyHeader)=)</para>
<para>;</para>
<para>; Remove all headers that begin with 'X-My'.</para>
<para>exten => 1,1,Set(PJSIP_HEADER(remove,X-My*)=)</para>
<para>;</para>
<para>; Remove all previously added headers.</para>
<para>exten => 1,1,Set(PJSIP_HEADER(remove,*)=)</para>
<para>;</para>
<example title="Set somevar to the value of the From header">
exten => 1,1,Set(somevar=${PJSIP_HEADER(read,From)})
</example>
<example title="Set via2 to the value of the 2nd Via header">
exten => 1,1,Set(via2=${PJSIP_HEADER(read,Via,2)})
</example>
<example title="Set xhdr to the value of the 1st X-header">
exten => 1,1,Set(xhdr=${PJSIP_HEADER(read,X-*,1)})
</example>
<example title="Add an X-Myheader header with the value of myvalue">
exten => 1,1,Set(PJSIP_HEADER(add,X-MyHeader)=myvalue)
</example>
<example title="Add an X-Myheader header with an empty value">
exten => 1,1,Set(PJSIP_HEADER(add,X-MyHeader)=)
</example>
<example title="Update the value of the header named X-Myheader to newvalue">
; 'X-Myheader' must already exist or the call will fail.
exten => 1,1,Set(PJSIP_HEADER(update,X-MyHeader)=newvalue)
</example>
<example title="Remove all headers whose names exactly match X-MyHeader">
exten => 1,1,Set(PJSIP_HEADER(remove,X-MyHeader)=)
</example>
<example title="Remove all headers that begin with X-My">
exten => 1,1,Set(PJSIP_HEADER(remove,X-My*)=)
</example>
<example title="Remove all previously added headers">
exten => 1,1,Set(PJSIP_HEADER(remove,*)=)
</example>
<note><para>The <literal>remove</literal> action can be called by reading
<emphasis>or</emphasis> writing PJSIP_HEADER.</para>
<para>;</para>
<para>; Display the number of headers removed</para>
<para>exten => 1,1,Verbose( Removed ${PJSIP_HEADER(remove,X-MyHeader)} headers)</para>
<para>;</para>
<para>; Set a variable to the number of headers removed</para>
<para>exten => 1,1,Set(count=${PJSIP_HEADER(remove,X-MyHeader)})</para>
<para>;</para>
<para>; Just remove them ignoring any count</para>
<para>exten => 1,1,Set(=${PJSIP_HEADER(remove,X-MyHeader)})</para>
<para>exten => 1,1,Set(PJSIP_HEADER(remove,X-MyHeader)=)</para>
<para>;</para>
</note>
<emphasis>or</emphasis> writing PJSIP_HEADER.</para></note>
<example title="Display the number of headers removed">
exten => 1,1,Verbose( Removed ${PJSIP_HEADER(remove,X-MyHeader)} headers)
</example>
<example title="Set a variable to the number of headers removed">
exten => 1,1,Set(count=${PJSIP_HEADER(remove,X-MyHeader)})
</example>
<example title="Just remove them ignoring any count">
exten => 1,1,Set(=${PJSIP_HEADER(remove,X-MyHeader)})
exten => 1,1,Set(PJSIP_HEADER(remove,X-MyHeader)=)
</example>
<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>
<para>Example:</para>
<para>;</para>
<para>[handler]</para>
<para>exten => addheader,1,Set(PJSIP_HEADER(add,X-MyHeader)=myvalue)</para>
<para>exten => addheader,2,Set(PJSIP_HEADER(add,X-MyHeader2)=myvalue2)</para>
<para>;</para>
<para>[somecontext]</para>
<para>exten => 1,1,Dial(PJSIP/${EXTEN},,b(handler^addheader^1))</para>
<para>;</para>
</note>
channel call PJSIP_HEADER in a pre-dial handler. </para></note>
<example title="Set headers on callee channel">
[handler]
exten => addheader,1,Set(PJSIP_HEADER(add,X-MyHeader)=myvalue)
exten => addheader,2,Set(PJSIP_HEADER(add,X-MyHeader2)=myvalue2)
[somecontext]
exten => 1,1,Dial(PJSIP/${EXTEN},,b(handler^addheader^1))
</example>
</description>
</function>
<function name="PJSIP_HEADERS" language="en_US">