--- IO-AIO/AIO.pm	2011/03/27 10:26:08	1.189
+++ IO-AIO/AIO.pm	2011/05/26 04:15:37	1.193
@@ -670,8 +670,8 @@
 
 =item IO::AIO::READDIR_DENTS
 
-When this flag is off, then the callback gets an arrayref with of names
-only (as with C<aio_readdir>), otherwise it gets an arrayref with
+When this flag is off, then the callback gets an arrayref consisting of
+names only (as with C<aio_readdir>), otherwise it gets an arrayref with
 C<[$name, $type, $inode]> arrayrefs, each describing a single directory
 entry in more detail.
 
@@ -694,13 +694,13 @@
 =item IO::AIO::READDIR_DIRS_FIRST
 
 When this flag is set, then the names will be returned in an order where
-likely directories come first. This is useful when you need to quickly
-find directories, or you want to find all directories while avoiding to
-stat() each entry.
+likely directories come first, in optimal stat order. This is useful when
+you need to quickly find directories, or you want to find all directories
+while avoiding to stat() each entry.
 
 If the system returns type information in readdir, then this is used
-to find directories directly.  Otherwise, likely directories are files
-beginning with ".", or otherwise files with no dots, of which files with
+to find directories directly. Otherwise, likely directories are names
+beginning with ".", or otherwise names with no dots, of which names with
 short names are tried first.
 
 =item IO::AIO::READDIR_STAT_ORDER
@@ -1408,16 +1408,24 @@
 
 =item IO::AIO::poll_cb
 
-Process some outstanding events on the result pipe. You have to call this
-regularly. Returns C<0> if all events could be processed, or C<-1> if it
-returned earlier for whatever reason. Returns immediately when no events
-are outstanding. The amount of events processed depends on the settings of
-C<IO::AIO::max_poll_req> and C<IO::AIO::max_poll_time>.
+Process some outstanding events on the result pipe. You have to call
+this regularly. Returns C<0> if all events could be processed (or there
+were no events to process), or C<-1> if it returned earlier for whatever
+reason. Returns immediately when no events are outstanding. The amount of
+events processed depends on the settings of C<IO::AIO::max_poll_req> and
+C<IO::AIO::max_poll_time>.
 
 If not all requests were processed for whatever reason, the filehandle
 will still be ready when C<poll_cb> returns, so normally you don't have to
 do anything special to have it called later.
 
+Apart from calling C<IO::AIO::poll_cb> when the event filehandle becomes
+ready, it can be beneficial to call this function from loops which submit
+a lot of requests, to make sure the results get processed when they become
+available and not just when the loop is finished and the event loop takes
+over again. This function returns very fast when there are no outstanding
+requests.
+
 Example: Install an Event watcher that automatically calls
 IO::AIO::poll_cb with high priority (more examples can be found in the
 SYNOPSIS section, at the top of this document):