--- Coro/Coro.pm	2001/07/03 02:53:34	1.1
+++ Coro/Coro.pm	2001/07/10 01:43:21	1.5
@@ -1,13 +1,35 @@
 =head1 NAME
 
-Coro - create an manage coroutines
+Coro - create and manage coroutines
 
 =head1 SYNOPSIS
 
  use Coro;
 
+ $new = new Coro sub {
+    print "in coroutine, switching back\n";
+    $Coro::main->resume;
+    print "in coroutine again, switching back\n";
+    $Coro::main->resume;
+ };
+
+ print "in main, switching to coroutine\n";
+ $new->resume;
+ print "back in main, switch to coroutine again\n";
+ $new->resume;
+ print "back in main\n";
+
 =head1 DESCRIPTION
 
+This module implements coroutines. Coroutines, similar to continuations,
+allow you to run more than one "thread of execution" in parallel. Unlike
+threads this, only voluntary switching is used so locking problems are
+greatly reduced.
+
+Although this is the "main" module of the Coro family it provides only
+low-level functionality. See L<Coro::Process> and related modules for a
+more useful process abstraction including scheduling.
+
 =over 4
 
 =cut
@@ -15,7 +37,7 @@
 package Coro;
 
 BEGIN {
-   $VERSION = 0.01;
+   $VERSION = 0.03;
 
    require XSLoader;
    XSLoader::load Coro, $VERSION;
@@ -47,7 +69,7 @@
 $error_coro = undef;
 
 $error = _newprocess {
-   print STDERR "FATAL: $error_msg, program aborted\n";
+   print STDERR "FATAL: $error_msg\nprogram aborted\n";
    exit 250;
 };
 
@@ -70,7 +92,7 @@
             ($error_msg, $error_coro) = ($@, $current);
             $error->resume;
          }
-      } while ();
+      } while (1);
    }, $class;
 }
 
@@ -82,6 +104,9 @@
 
 my $prev;
 
+# I call the _transfer function from a pelr function
+# because that way perl saves all important things on
+# the stack.
 sub resume {
    $prev = $current; $current = $_[0];
    _transfer($prev, $current);
@@ -95,6 +120,10 @@
 
 This module has not yet been extensively tested.
 
+=head1 SEE ALSO
+
+L<Coro::Process>, L<Coro::Signal>.
+
 =head1 AUTHOR
 
  Marc Lehmann <pcg@goof.com>