From e19206dbbcf18caa8799630e9e9fcc73f7b5c32a Mon Sep 17 00:00:00 2001
From: dkf <donal.k.fellows@manchester.ac.uk>
Date: Sun, 1 Nov 2009 00:26:02 +0000
Subject: Improve with more explanation of what's going on.

---
 doc/coroutine.n | 44 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

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
-- 
cgit v0.12