--- IO-AIO/AIO.pm	2006/10/22 13:52:11	1.61
+++ IO-AIO/AIO.pm	2006/10/22 21:13:47	1.62
@@ -605,17 +605,25 @@
 This makes it very easy to create composite requests (see the source of
 C<aio_move> for an application) that work and feel like simple requests.
 
-The IO::AIO::GRP objects will be cleaned up during calls to
+=over 4
+
+=item * The IO::AIO::GRP objects will be cleaned up during calls to
 C<IO::AIO::poll_cb>, just like any other request.
 
-They can be canceled like any other request. Canceling will cancel not
+=item * They can be canceled like any other request. Canceling will cancel not
 only the request itself, but also all requests it contains.
 
-They can also can also be added to other IO::AIO::GRP objects.
+=item * They can also can also be added to other IO::AIO::GRP objects.
 
-You must not add requests to a group from within the group callback (or
+=item * You must not add requests to a group from within the group callback (or
 any later time).
 
+=item * This does not harmonise well with C<max_outstanding>, so best do
+not combine C<aio_group> with it. Groups and feeders are recommended for
+this kind of concurrency-limiting.
+
+=back
+
 Their lifetime, simplified, looks like this: when they are empty, they
 will finish very quickly. If they contain only requests that are in the
 C<done> state, they will also finish. Otherwise they will continue to
@@ -786,6 +794,8 @@
 
 =item $oldnreqs = IO::AIO::max_outstanding $nreqs
 
+[DEPRECATED]
+
 Sets the maximum number of outstanding requests to C<$nreqs>. If you
 try to queue up more than this number of requests, the caller will block until
 some requests have been handled.
@@ -794,6 +804,10 @@
 queue up many requests in a loop it often improves speed if you set
 this to a relatively low number, such as C<100>.
 
+This function does not work well together with C<aio_group>'s, and their
+feeder interface is better suited to limiting concurrency, so do not use
+this function.
+
 Under normal circumstances you don't need to call this function.
 
 =back