func_cut: Add example to documentation.

This adds an example to the XML documentation clarifying usage
of the CUT function to address a common misusage.

(cherry picked from commit 3e91137404b561aec0b697fb65806e6ff2457287)

diff --git a/funcs/func_cut.c b/funcs/func_cut.c
index f8bc4941ecb2203b6b353c6cdb0acdea66508482..a0d508d575ad243ed68e0e1d9d7d743fe1dbb5dc 100644 (file)
--- a/funcs/func_cut.c
+++ b/funcs/func_cut.c
@@ -75,6 +75,10 @@
                </syntax>
                <description>
                        <para>Cut out information from a string (<replaceable>varname</replaceable>), based upon a named delimiter.</para>
+                                       <example title="The 'varname' parameter can only accept a variable name, not a variable expression">
+                               exten => s,1,Set(foo=${CUT(bar,,2)}); This is correct syntax
+                               exten => s,2,Set(foo=${CUT(${bar},,2)}); This is invalid syntax (unless bar contains the name of another variable)
+                                       </example>
                </description>
        </function>
  ***/