TIP 696 - partition return codes between core and non-core

4 files changed, 20 insertions, 11 deletions

diff --git a/doc/CrtCommand.3 b/doc/CrtCommand.3
index d15a920..5d25667 100644
--- a/doc/CrtCommand.3
+++ b/doc/CrtCommand.3
@@ -102,9 +102,12 @@ version 8.1 of Tcl.
 .PP
 \fIProc\fR must return an integer code that is expected to be one of
 \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
-\fBTCL_CONTINUE\fR.  See the Tcl overview man page
-for details on what these codes mean.  Most normal commands will only
-return \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
+\fBTCL_CONTINUE\fR. See the \fBreturn\fR man page for details on
+what these codes mean and the use of extended values for an extension's
+private use. Most normal commands will only return \fBTCL_OK\fR
+or \fBTCL_ERROR\fR.
+.PP
+In addition, \fIproc\fR must set
 the interpreter result;
 in the case of a \fBTCL_OK\fR return code this gives the result
 of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3
index 522f903..b28d901 100644
--- a/doc/CrtObjCmd.3
+++ b/doc/CrtObjCmd.3
@@ -132,9 +132,10 @@ that \fIobjv\fR[\fB2\fR] points at, but will not change where
 .PP
 \fIproc\fR must return an integer code that is either \fBTCL_OK\fR,
 \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.
-See the Tcl overview man page
-for details on what these codes mean.  Most normal commands will only
-return \fBTCL_OK\fR or \fBTCL_ERROR\fR.
+See the \fBreturn\fR man page for details on what these codes mean and the
+use of extended values for an extension's private use. Most normal commands
+will only return \fBTCL_OK\fR or \fBTCL_ERROR\fR.
+.PP
 In addition, if \fIproc\fR needs to return a non-empty result,
 it can call \fBTcl_SetObjResult\fR to set the interpreter's result.
 In the case of a \fBTCL_OK\fR return code this gives the result
diff --git a/doc/catch.n b/doc/catch.n
index 8d885d4..0a2c513 100644
--- a/doc/catch.n
+++ b/doc/catch.n
@@ -30,10 +30,12 @@ return codes: 1 (\fBTCL_ERROR\fR), 2 (\fBTCL_RETURN\fR), 3 (\fBTCL_BREAK\fR),
 and 4 (\fBTCL_CONTINUE\fR).  Errors during evaluation of a script are indicated
 by a return code of \fBTCL_ERROR\fR.  The other exceptional return codes are
 returned by the \fBreturn\fR, \fBbreak\fR, and \fBcontinue\fR commands
-and in other special situations as documented.  Tcl packages can define
-new commands that return other integer values as return codes as well,
-and scripts that make use of the \fBreturn \-code\fR command can also
-have return codes other than the five defined by Tcl.
+and in other special situations as documented.
+New commands defined by Tcl packages as well as scripts that make
+use of the \fBreturn \-code\fR  command can return other integer
+values as the return code. These must however lie outside the range
+reserved for Tcl as documented for the \fBreturn\fR command.
+
 .PP
 If the \fIresultVarName\fR argument is given, then the variable it names is
 set to the result of the script evaluation.  When the return code from the
diff --git a/doc/return.n b/doc/return.n
index 9bf1ae2..d285e87 100644
--- a/doc/return.n
+++ b/doc/return.n
@@ -78,7 +78,10 @@ were the command \fBcontinue\fR.
 \fIvalue\fR
 .
 \fIValue\fR must be an integer;  it will be returned as the
-return code for the current procedure.
+return code for the current procedure. Applications
+and packages should use values in the range 5 to 1073741823 (0x3fffffff)
+for their own purposes. Values outside this range are reserved
+for use by Tcl.
 .LP
 When a procedure wants to signal that it has received invalid
 arguments from its caller, it may use \fBreturn -code error\fR