--- AnyEvent/lib/AnyEvent.pm	2008/04/25 13:39:08	1.83
+++ AnyEvent/lib/AnyEvent.pm	2008/04/25 13:51:32	1.85
@@ -143,15 +143,19 @@
 You can create an I/O watcher by calling the C<< AnyEvent->io >> method
 with the following mandatory key-value pairs as arguments:
 
-C<fh> the Perl I<file handle> (I<not> file descriptor) to watch for
-events. C<poll> must be a string that is either C<r> or C<w>, which
-creates a watcher waiting for "r"eadable or "w"ritable events,
+C<fh> the Perl I<file handle> (I<not> file descriptor) to watch
+for events. C<poll> must be a string that is either C<r> or C<w>,
+which creates a watcher waiting for "r"eadable or "w"ritable events,
 respectively. C<cb> is the callback to invoke each time the file handle
 becomes ready.
 
+Although the callback might get passed parameters, their value and
+presence is undefined and you cannot rely on them. Portable AnyEvent
+callbacks cannot use arguments passed to I/O watcher callbacks.
+
 The I/O watcher might use the underlying file descriptor or a copy of it.
-It is not allowed to close a file handle as long as any watcher is active
-on the underlying file descriptor.
+You must not close a file handle as long as any watcher is active on the
+underlying file descriptor.
 
 Some event loops issue spurious readyness notifications, so you should
 always use non-blocking calls when reading/writing from/to your file
@@ -172,8 +176,12 @@
 method with the following mandatory arguments:
 
 C<after> specifies after how many seconds (fractional values are
-supported) should the timer activate. C<cb> the callback to invoke in that
-case.
+supported) the callback should be invoked. C<cb> is the callback to invoke
+in that case.
+
+Although the callback might get passed parameters, their value and
+presence is undefined and you cannot rely on them. Portable AnyEvent
+callbacks cannot use arguments passed to time watcher callbacks.
 
 The timer callback will be invoked at most once: if you want a repeating
 timer you have to create a new watcher (this is a limitation by both Tk
@@ -228,6 +236,10 @@
 I<name> without any C<SIG> prefix, C<cb> is the Perl callback to
 be invoked whenever a signal occurs.
 
+Although the callback might get passed parameters, their value and
+presence is undefined and you cannot rely on them. Portable AnyEvent
+callbacks cannot use arguments passed to signal watcher callbacks.
+
 Multiple signal occurances can be clumped together into one callback
 invocation, and callback invocation will be synchronous. synchronous means
 that it might take a while until the signal gets handled by the process,
@@ -251,7 +263,8 @@
 watches for any child process exit). The watcher will trigger as often
 as status change for the child are received. This works by installing a
 signal handler for C<SIGCHLD>. The callback will be called with the pid
-and exit status (as returned by waitpid).
+and exit status (as returned by waitpid), so unlike other watcher types,
+you I<can> rely on child watcher callback arguments.
 
 There is a slight catch to child watchers, however: you usually start them
 I<after> the child process was created, and this means the process could
@@ -948,10 +961,9 @@
 boost.
 
 C<EV> is the sole leader regarding speed and memory use, which are both
-maximal/minimal, respectively. Even when going through AnyEvent, there are
-only two event loops that use slightly less memory (the C<Event> module
-natively and the pure perl backend), and no faster event models, not even
-C<Event> natively.
+maximal/minimal, respectively. Even when going through AnyEvent, it uses
+far less memory than any other event loop and is still faster than Event
+natively.
 
 The pure perl implementation is hit in a few sweet spots (both the
 zero timeout and the use of a single fd hit optimisations in the perl