changeset 27972:8f33435cfb00

doc: * doc/interpreter/func.txi: Reorder nodes for clarity.
author Kai T. Ohlhus <k.ohlhus@gmail.com>
date Wed, 22 Jan 2020 00:26:59 +0900
parents ec769a7ab9fb
children 8a07553faf2b
files doc/interpreter/func.txi
diffstat 1 files changed, 94 insertions(+), 94 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/func.txi	Tue Jan 21 09:20:15 2020 -0600
+++ b/doc/interpreter/func.txi	Wed Jan 22 00:26:59 2020 +0900
@@ -31,11 +31,11 @@
 @menu
 * Introduction to Function and Script Files::
 * Defining Functions::
+* Returning from a Function::
 * Multiple Return Values::
+* Variable-length Return Lists::
 * Variable-length Argument Lists::
 * Ignoring Arguments::
-* Variable-length Return Lists::
-* Returning from a Function::
 * Default Arguments::
 * Function Files::
 * Script Files::
@@ -276,6 +276,54 @@
 
 @DOCSTRING(silent_functions)
 
+@node Returning from a Function
+@section Returning from a Function
+
+The body of a user-defined function can contain a @code{return} statement.
+This statement returns control to the rest of the Octave program.  It
+looks like this:
+
+@example
+return
+@end example
+
+Unlike the @code{return} statement in C, Octave's @code{return}
+statement cannot be used to return a value from a function.  Instead,
+you must assign values to the list of return variables that are part of
+the @code{function} statement.  The @code{return} statement simply makes
+it easier to exit a function from a deeply nested loop or conditional
+statement.
+
+Here is an example of a function that checks to see if any elements of a
+vector are nonzero.
+
+@example
+@group
+function retval = any_nonzero (v)
+  retval = 0;
+  for i = 1:length (v)
+    if (v (i) != 0)
+      retval = 1;
+      return;
+    endif
+  endfor
+  printf ("no nonzero elements found\n");
+endfunction
+@end group
+@end example
+
+Note that this function could not have been written using the
+@code{break} statement to exit the loop once a nonzero value is found
+without adding extra logic to avoid printing the message if the vector
+does contain a nonzero element.
+
+@deftypefn {} {} return
+When Octave encounters the keyword @code{return} inside a function or
+script, it returns control to the caller immediately.  At the top level,
+the return statement is ignored.  A @code{return} statement is assumed
+at the end of every function definition.
+@end deftypefn
+
 @node Multiple Return Values
 @section Multiple Return Values
 
@@ -415,6 +463,50 @@
 @DOCSTRING(inputParser)
 
 @anchor{XREFvarargin} @anchor{XREFvarargout}
+
+@node Variable-length Return Lists
+@section Variable-length Return Lists
+@cindex variable-length return lists
+@cindex @code{varargout}
+
+It is possible to return a variable number of output arguments from a
+function using a syntax that's similar to the one used with the
+special @code{varargin} parameter name.  To let a function return a
+variable number of output arguments the special output parameter name
+@code{varargout} is used.  As with @code{varargin}, @code{varargout} is
+a cell array that will contain the requested output arguments.
+
+As an example the following function sets the first output argument to
+1, the second to 2, and so on.
+
+@example
+@group
+function varargout = one_to_n ()
+  for i = 1:nargout
+    varargout@{i@} = i;
+  endfor
+endfunction
+@end group
+@end example
+
+@noindent
+When called this function returns values like this
+
+@example
+@group
+[a, b, c] = one_to_n ()
+     @result{} a =  1
+     @result{} b =  2
+     @result{} c =  3
+@end group
+@end example
+
+If @code{varargin} (@code{varargout}) does not appear as the last
+element of the input (output) parameter list, then it is not special,
+and is handled the same as any other parameter name.
+
+@DOCSTRING(deal)
+
 @node Variable-length Argument Lists
 @section Variable-length Argument Lists
 @cindex variable-length argument lists
@@ -585,98 +677,6 @@
 @end example
 
 @DOCSTRING(isargout)
-
-@node Variable-length Return Lists
-@section Variable-length Return Lists
-@cindex variable-length return lists
-@cindex @code{varargout}
-
-It is possible to return a variable number of output arguments from a
-function using a syntax that's similar to the one used with the
-special @code{varargin} parameter name.  To let a function return a
-variable number of output arguments the special output parameter name
-@code{varargout} is used.  As with @code{varargin}, @code{varargout} is
-a cell array that will contain the requested output arguments.
-
-As an example the following function sets the first output argument to
-1, the second to 2, and so on.
-
-@example
-@group
-function varargout = one_to_n ()
-  for i = 1:nargout
-    varargout@{i@} = i;
-  endfor
-endfunction
-@end group
-@end example
-
-@noindent
-When called this function returns values like this
-
-@example
-@group
-[a, b, c] = one_to_n ()
-     @result{} a =  1
-     @result{} b =  2
-     @result{} c =  3
-@end group
-@end example
-
-If @code{varargin} (@code{varargout}) does not appear as the last
-element of the input (output) parameter list, then it is not special,
-and is handled the same as any other parameter name.
-
-@DOCSTRING(deal)
-
-@node Returning from a Function
-@section Returning from a Function
-
-The body of a user-defined function can contain a @code{return} statement.
-This statement returns control to the rest of the Octave program.  It
-looks like this:
-
-@example
-return
-@end example
-
-Unlike the @code{return} statement in C, Octave's @code{return}
-statement cannot be used to return a value from a function.  Instead,
-you must assign values to the list of return variables that are part of
-the @code{function} statement.  The @code{return} statement simply makes
-it easier to exit a function from a deeply nested loop or conditional
-statement.
-
-Here is an example of a function that checks to see if any elements of a
-vector are nonzero.
-
-@example
-@group
-function retval = any_nonzero (v)
-  retval = 0;
-  for i = 1:length (v)
-    if (v (i) != 0)
-      retval = 1;
-      return;
-    endif
-  endfor
-  printf ("no nonzero elements found\n");
-endfunction
-@end group
-@end example
-
-Note that this function could not have been written using the
-@code{break} statement to exit the loop once a nonzero value is found
-without adding extra logic to avoid printing the message if the vector
-does contain a nonzero element.
-
-@deftypefn {} {} return
-When Octave encounters the keyword @code{return} inside a function or
-script, it returns control to the caller immediately.  At the top level,
-the return statement is ignored.  A @code{return} statement is assumed
-at the end of every function definition.
-@end deftypefn
-
 @node Default Arguments
 @section Default Arguments
 @cindex default arguments