torben Sun Jan 13 19:05:19 2002 EDT
Modified files:
/phpdoc TODO
/phpdoc/en/language control-structures.xml functions.xml
Log:
Document that return returns from more than just functions.
I used <function> for return in the same spirit that <function> is used
for other constructs which are not functions--echo, print, etc--and noted
that you don't need the parentheses with it. If anybody has a good argument
for using another tag, mention it on the doc list and we'll chat. :)
Index: phpdoc/TODO
diff -u phpdoc/TODO:1.14 phpdoc/TODO:1.15
--- phpdoc/TODO:1.14 Thu Jan 10 08:52:55 2002
+++ phpdoc/TODO Sun Jan 13 19:05:18 2002
@@ -34,8 +34,6 @@
GENERAL:
- - Document that "return" returns from any file, not only
- included files.
- Document php://stdout etc feature for file functions.
- Update setcookie
- Document the diffs between strip[c]slashes(). Maybe just document
Index: phpdoc/en/language/control-structures.xml
diff -u phpdoc/en/language/control-structures.xml:1.48
phpdoc/en/language/control-structures.xml:1.49
--- phpdoc/en/language/control-structures.xml:1.48 Thu Dec 20 18:17:37 2001
+++ phpdoc/en/language/control-structures.xml Sun Jan 13 19:05:18 2002
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.48 $ -->
+<!-- $Revision: 1.49 $ -->
<chapter id="control-structures">
<title>Control Structures</title>
@@ -979,7 +979,47 @@
</simpara>
</sect2>
</sect1>
-
+
+ <sect1 id="functions.return">
+ <title>return</title>
+ <simpara>
+ If called from within a function, the <function>return</function>
+ statement immediately ends execution of the current function, and
+ returns its argument as the value of the function
+ call. <function>return</function> will also end the execution of
+ an <function>eval</function> statement or script file.
+ </simpara>
+ <simpara>
+ If called from the global scope, then execution of the current
+ script file is ended. If the current script file was
+ <function>include</function>ed or <function>require</function>ed,
+ then control is passed back to the calling file. Furthermore, if
+ the current script file was <function>include</function>ed, then
+ the value given to <function>return</function> will be returned as
+ the value of the <function>include</function> call. If
+ <function>return</function> is called from within the main script
+ file, then script execution ends. If the current script file was
+ named by the <link
+ linkend="ini.auto-prepend-file">auto_prepend_file</link> or <link
+ linkend="ini.auto-append-file">auto_append_file</link>
+ configuration options in <link linkend="configuration.file">the
+ configuration file</link>, then that script file's execution is
+ ended.
+ </simpara>
+ <simpara>For more information, see <link
+ linkend="functions.returning-values">Returning values</link>.
+ </simpara>
+ <note>
+ <simpara>
+ Note that since <function>return</function> is a language
+ construct and not a function, the parentheses surrounding its
+ arguments are <emphasis>not</emphasis> required--in fact, it is
+ more common to leave them out than to use them, although it
+ doesn't matter one way or the other.
+ </simpara>
+ </note>
+ </sect1>
+
<sect1 id="function.require">
<title><function>require</function></title>
<simpara>
Index: phpdoc/en/language/functions.xml
diff -u phpdoc/en/language/functions.xml:1.20 phpdoc/en/language/functions.xml:1.21
--- phpdoc/en/language/functions.xml:1.20 Wed Dec 12 15:47:38 2001
+++ phpdoc/en/language/functions.xml Sun Jan 13 19:05:19 2002
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.20 $ -->
+<!-- $Revision: 1.21 $ -->
<chapter id="functions">
<title>Functions</title>
@@ -261,8 +261,10 @@
<para>
Values are returned by using the optional return statement. Any
- type may be returned, including lists and objects.
-
+ type may be returned, including lists and objects. This causes the
+ function to end its execution immediately and pass control back to
+ the line from which it was called. See <function>return</function>
+ for more information.
<informalexample>
<programlisting role="php">
<