Yet more doc update backporting

1 files changed, 85 insertions, 33 deletions

diff --git a/doc/return.n b/doc/return.n
index 2ea381d..685e0be 100644
--- a/doc/return.n
+++ b/doc/return.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: return.n,v 1.3 2000/09/07 14:27:51 poenitz Exp $
+'\" RCS: @(#) $Id: return.n,v 1.3.18.1 2004/10/27 14:23:58 dkf Exp $
 '\" 
 .so man.macros
 .TH return n 7.0 Tcl "Tcl Built-In Commands"
@@ -23,43 +23,45 @@ Return immediately from the current procedure
 (or top-level command or \fBsource\fR command),
 with \fIstring\fR as the return value.  If \fIstring\fR is not specified then
 an empty string will be returned as result.
-
-.SH "EXCEPTIONAL RETURNS"
+.SH "EXCEPTIONAL RETURN CODES"
 .PP
+In addition to the result of a procedure, the return
+code of a procedure may also be set by \fBreturn\fR
+through use of the \fB-code\fR option.
 In the usual case where the \fB\-code\fR option isn't
-specified the procedure will return normally (its completion
-code will be TCL_OK).
+specified the procedure will return normally.
 However, the \fB\-code\fR option may be used to generate an
 exceptional return from the procedure.
 \fICode\fR may have any of the following values:
-.TP 10
-\fBok\fR
-Normal return:  same as if the option is omitted.
-.TP 10
-\fBerror\fR
-Error return: same as if the \fBerror\fR command were used to
-terminate the procedure, except for handling of \fBerrorInfo\fR
-and \fBerrorCode\fR variables (see below).
-.TP 10
-\fBreturn\fR
-The current procedure will return with a completion code of
-TCL_RETURN, so that the procedure that invoked it will return
-also.
-.TP 10
-\fBbreak\fR
-The current procedure will return with a completion code of
-TCL_BREAK, which will terminate the innermost nested loop in
-the code that invoked the current procedure.
-.TP 10
-\fBcontinue\fR
-The current procedure will return with a completion code of
-TCL_CONTINUE, which will terminate the current iteration of
-the innermost nested loop in the code that invoked the current
-procedure.
-.TP 10
+.TP 13
+\fBok (or 0)\fR
+Normal return:  same as if the option is omitted.  The return code
+of the procedure is 0 (\fBTCL_OK\fR).
+.TP 13
+\fBerror (1)\fR
+Error return: the return code of the procedure is 1 (\fBTCL_ERROR\fR).
+The procedure command behaves in its calling context as if it
+were the command \fBerror \fIresult\fR.  See below for additional
+options.
+.TP 13
+\fBreturn (2)\fR
+The return code of the procedure is 2 (\fBTCL_RETURN\fR).  The
+procedure command behaves in its calling context as if it
+were the command \fBreturn\fR (with no arguments).
+.TP 13
+\fBbreak (3)\fR
+The return code of the procedure is 3 (\fBTCL_BREAK\fR).  The
+procedure command behaves in its calling context as if it
+were the command \fBbreak\fR.
+.TP 13
+\fBcontinue (4)\fR
+The return code of the procedure is 4 (\fBTCL_CONTINUE\fR).  The
+procedure command behaves in its calling context as if it
+were the command \fBcontinue\fR.
+.TP 13
 \fIvalue\fR
 \fIValue\fR must be an integer;  it will be returned as the
-completion code for the current procedure.
+return code for the current procedure.
 .LP
 The \fB\-code\fR option is rarely used.
 It is provided so that procedures that implement
@@ -84,9 +86,59 @@ If the \fB\-errorcode\fR option is specified then \fIcode\fR provides
 a value for the \fBerrorCode\fR variable.
 If the option is not specified then \fBerrorCode\fR will
 default to \fBNONE\fR.
+.SH EXAMPLES
+First, a simple example of using \fBreturn\fR to return from a
+procedure, interrupting the procedure body.
+.CS
+proc printOneLine {} {
+   puts "line 1"    ;# This line will be printed.
+   \fBreturn\fR		
+   puts "line 2"    ;# This line will not be printed.
+}
+.CE
+.PP
+Next, an example of using \fBreturn\fR to set the value
+returned by the procedure.
+.CS
+proc returnX {} {\fBreturn\fR X}
+puts [returnX]    ;# prints "X"
+.CE
+.PP
+Next, a more complete example, using \fBreturn -code error\fR
+to report invalid arguments.
+.CS
+proc factorial {n} {
+   if {![string is integer $n] || ($n < 0)} {
+      \fBreturn\fR -code error \\
+            "expected non-negative integer,\\
+             but got \\"$n\\""
+   }
+   if {$n < 2} {
+      \fBreturn\fR 1
+   }
+   set m [expr {$n - 1}]
+   set code [catch {factorial $m} factor]
+   if {$code != 0} {
+      \fBreturn\fR -code $code $factor
+   }
+   set product [expr {$n * $factor}]
+   if {$product < 0} {
+      \fBreturn\fR -code error \\
+            "overflow computing factorial of $n"
+   }
+   \fBreturn\fR $product
+}
+.CE
+.PP
+Next, a procedure replacement for \fBbreak\fR.
+.CS
+proc myBreak {} {
+   \fBreturn\fR -code break
+}
+.CE
 
 .SH "SEE ALSO"
-break(n), continue(n), error(n), proc(n)
+break(n), catch(n), continue(n), error(n), proc(n), source(n), tclvars(n)
 
 .SH KEYWORDS
-break, continue, error, procedure, return
+break, catch, continue, error, procedure, return