TIP #348 IMPLEMENTATION - Substituted error stack

1 files changed, 17 insertions, 1 deletions

diff --git a/doc/return.n b/doc/return.n
index 4f77135..8d0d96c 100644
--- a/doc/return.n
+++ b/doc/return.n
@@ -6,7 +6,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.25 2010/01/20 13:42:17 dkf Exp $
+'\" RCS: @(#) $Id: return.n,v 1.26 2010/04/05 19:44:45 ferrieux Exp $
 '\" 
 .so man.macros
 .TH return n 8.5 Tcl "Tcl Built-In Commands"
@@ -138,6 +138,22 @@ the value of \fB\-errorinfo\fR in a return options dictionary captured
 by the \fBcatch\fR command (or from the copy of that information
 stored in the global variable \fBerrorInfo\fR).
 .TP
+\fB\-errorstack \fIlist\fR
+.
+The \fB\-errorstack\fR option receives special treatment only when the value
+of the \fB\-code\fR option is \fBTCL_ERROR\fR.  Then \fIlist\fR is the initial
+error stack, recording actual argument values passed to each proc level.  The error stack will
+also be reachable through [info errorstack].
+If no \fB\-errorstack\fR option is provided to \fBreturn\fR when
+the \fB\-code error\fR option is provided, Tcl will provide its own
+initial error stack in the entry for \fB\-errorstack\fR.  Tcl's
+initial error stack will include only the call to the procedure, and
+stack unwinding will append information about higher stack levels, but
+there will be no information about the context of the error within
+the procedure.  Typically the \fIlist\fR value is supplied from
+the value of \fB\-errorstack\fR in a return options dictionary captured
+by the \fBcatch\fR command (or from the copy of that information from [info errorstack]).
+.TP
 \fB\-level \fIlevel\fR
 .
 The \fB\-level\fR and \fB\-code\fR options work together to set the return