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

funcs/func_shell.c

 /*
  * 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");