Improve with more explanation of what's going on.

1 files changed, 43 insertions, 1 deletions

diff --git a/doc/coroutine.n b/doc/coroutine.n
index 08662c8..f310e13 100644
--- a/doc/coroutine.n
+++ b/doc/coroutine.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: coroutine.n,v 1.2 2009/03/26 10:43:47 dkf Exp $
+'\" RCS: @(#) $Id: coroutine.n,v 1.3 2009/11/01 00:26:02 dkf Exp $
 '\" 
 .so man.macros
 .TH coroutine n 8.6 Tcl "Tcl Built-In Commands"
@@ -42,6 +42,11 @@ the name of the current coroutine can be retrieved by using \fBinfo
 coroutine\fR. If there are deletion traces on variables in the coroutine's
 implementation, they will fire at the point when the coroutine is explicitly
 deleted (or, naturally, if the command returns conventionally).
+.PP
+At the point when \fIcommand\fR is called, the current namespace will be the
+global namespace and there will be no stack frames above it (in the sense of
+\fBupvar\fR and \fBuplevel\fR). However, which command to call will be
+determined in the namespace that the \fBcoroutine\fR command was called from.
 .SH EXAMPLES
 .PP
 This example shows a coroutine that will produce an infinite sequence of
@@ -104,6 +109,43 @@ for {set i 1} {$i <= 20} {incr i} {
     puts "prime#$i = [\fIeratosthenes\fR]"
 }
 .CE
+.SS "DETAILED SEMANTICS"
+.PP
+This example demonstrates that coroutines start from the global namespace, and
+that\fIcommand\fR resolution happens before the coroutine stack is created.
+.PP
+.CS
+proc report {where level} {
+    # Where was the caller called from?
+    set ns [uplevel 2 {namespace current}]
+    \fByield\fR "made $where $level context=$ns name=[info coroutine]"
+}
+proc example {} {
+    report outer [info level]
+}
+namespace eval demo {
+    proc example {} {
+        report inner [info level]
+    }
+    proc makeExample {} {
+        puts "making from [info level]"
+        puts [coroutine coroEg example]
+    }
+    makeExample
+}
+.CE
+.PP
+Which produces the output below. In particular, we can see that stack
+manipulation has occurred (comparing the levels from the first and second
+line) and that the parent level in the coroutine is the global namespace. We
+can also see that coroutine names are local to the current namespace if not
+qualified, and that coroutines may yield at depth (e.g., in called
+procedures).
+.PP
+.CS
+making from 2
+made inner 1 context=:: name=::demo::coroEg
+.CE
 .SH "SEE ALSO"
 apply(n), info(n), proc(n), return(n)
 .SH KEYWORDS