--- IO-AIO/AIO.pm	2011/05/19 23:57:12	1.191
+++ IO-AIO/AIO.pm	2011/05/26 04:15:37	1.193
@@ -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
@@ -1419,6 +1419,13 @@
 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):