Clarify documentation for function PASSTHRU

It is not apparent to the average user that the PASSTHRU function should not
be passed as ${PASSTHRU(string)} but just as PASSTHRU(string) to functions
which take a variable name and not its contents.

This patch clarifies the behavior in the documentation and provides an example.

(closes issue ASTERISK-21717)
Reported by: Richard Miller
patches:
  func_strings.diff uploaded by Richard Miller (license 5685)
........

Merged revisions 394302 from http://svn.asterisk.org/svn/asterisk/branches/1.8
........

Merged revisions 394303 from http://svn.asterisk.org/svn/asterisk/branches/11

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@394304 65c4cc65-6c06-0410-ace0-fbb531ad65f3

diff --git a/funcs/func_strings.c b/funcs/func_strings.c
index 9e486d6..937fe2b 100644 (file)
--- a/funcs/func_strings.c
+++ b/funcs/func_strings.c
@@ -165,6 +165,10 @@ AST_THREADSTORAGE(tmp_buf);
                        <para>Literally returns the given <replaceable>string</replaceable>.  The intent is to permit
                        other dialplan functions which take a variable name as an argument to be able to take a literal
                        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>
+                       <para>         ${CUT(PASSTHRU(${CUT(CHANNEL,-,1)}),/,2)}) will return 321</para>
                </description>
        </function>
        <function name="REGEX" language="en_US">