Improve documentation for the SHELL() dialplan function.

........

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

Merged revisions 370384 from http://svn.asterisk.org/svn/asterisk/branches/10

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

diff --git a/funcs/func_shell.c b/funcs/func_shell.c
index 2f34f62..bad10b3 100644 (file)
--- a/funcs/func_shell.c
+++ b/funcs/func_shell.c
@@ -1,7 +1,7 @@
 /*
  * Asterisk -- An open source telephony toolkit.
  *
- * Copyright (C) 2006, Digium, Inc.
+ * Copyright (C) 2006-2012, Digium, Inc.
  *
  * See http://www.asterisk.org for more information about
  * the Asterisk project. Please do not directly contact
@@ -16,9 +16,9 @@
 
 /*! \file
  *
- * SHELL function to return the value of a system call.
- * 
- * \note Inspiration and Guidance from Russell! Thank You! 
+ * SHELL function to return the output generated by a command issued to the system shell.
+ *
+ * \note Inspiration and Guidance from Russell! Thank You!
  *
  * \author Brandon Kruse <bkruse@digium.com>
  *
@@ -79,23 +79,22 @@ static int shell_helper(struct ast_channel *chan, const char *cmd, char *data,
 /*** DOCUMENTATION
        <function name="SHELL" language="en_US">
                <synopsis>
-                       Executes a command as if you were at a shell.
+                       Executes a command using the system shell and captures its output.
                </synopsis>
                <syntax>
                        <parameter name="command" required="true">
-                               <para>This is the argument to the function, the command you want to pass to the shell.</para>
+                               <para>The command that the shell should execute.</para>
                        </parameter>
                </syntax>
                <description>
-                       <para>Returns the value from a system command</para>
+                       <para>Collects the output generated by a command executed by the system shell</para>
                        <para>Example:  <literal>Set(foo=${SHELL(echo \bar\)})</literal></para>
-                       <note><para>When using the SHELL() dialplan function, your \SHELL\ is /bin/sh,
-                       which may differ as to the underlying shell, depending upon your production
-                       platform.  Also keep in mind that if you are using a common path, you should
-                       be mindful of race conditions that could result from two calls running
-                       SHELL() simultaneously.</para></note>
+                       <note><para>The command supplied to this function will be executed by the
+                       system's shell, typically specified in the SHELL environment variable. There
+                       are many different system shells available with somewhat different behaviors,
+                       so the output generated by this function may vary between platforms.</para></note>
                </description>
- 
+
        </function>
  ***/
 static struct ast_custom_function shell_function = {
@@ -113,5 +112,4 @@ static int load_module(void)
        return ast_custom_function_register(&shell_function);
 }
 
-AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Returns the output of a shell command");
-
+AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Collects the output generated by a command executed by the system shell");