--- AnyEvent/lib/AnyEvent.pm	2008/04/07 19:40:12	1.42
+++ AnyEvent/lib/AnyEvent.pm	2008/04/14 16:09:33	1.47
@@ -20,7 +20,7 @@
    $w->wait; # enters "main loop" till $condvar gets ->broadcast
    $w->broadcast; # wake up current and all future wait's
 
-=head1 WHY YOU SHOULD USE THIS MODULE
+=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
 
 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
 nowadays. So what is different about AnyEvent?
@@ -60,6 +60,10 @@
 offering the functionality that is useful, in as thin as a wrapper as
 technically possible.
 
+Of course, if you want lots of policy (this can arguably be somewhat
+useful) and you want to force your users to use the one and only event
+model, you should I<not> use this module.
+
 
 =head1 DESCRIPTION
 
@@ -177,16 +181,24 @@
 Wait (blocking if necessary) until the C<< ->broadcast >> method has been
 called on c<$cv>, while servicing other watchers normally.
 
-Not all event models support a blocking wait - some die in that case, so
-if you are using this from a module, never require a blocking wait, but
-let the caller decide wether the call will block or not (for example,
-by coupling condition variables with some kind of request results and
-supporting callbacks so the caller knows that getting the result will not
-block, while still suppporting blockign waits if the caller so desires).
-
 You can only wait once on a condition - additional calls will return
 immediately.
 
+Not all event models support a blocking wait - some die in that case
+(programs might want to do that so they stay interactive), so I<if you
+are using this from a module, never require a blocking wait>, but let the
+caller decide wether the call will block or not (for example, by coupling
+condition variables with some kind of request results and supporting
+callbacks so the caller knows that getting the result will not block,
+while still suppporting blocking waits if the caller so desires).
+
+Another reason I<never> to C<< ->wait >> in a module is that you cannot
+sensibly have two C<< ->wait >>'s in parallel, as that would require
+multiple interpreters or coroutines/threads, none of which C<AnyEvent>
+can supply (the coroutine-aware backends C<Coro::EV> and C<Coro::Event>
+explicitly support concurrent C<< ->wait >>'s from different coroutines,
+however).
+
 =item $cv->broadcast
 
 Flag the condition as ready - a running C<< ->wait >> and all further