--- libeio/eio.pod	2011/09/26 16:54:25	1.28
+++ libeio/eio.pod	2016/01/24 16:36:20	1.36
@@ -27,7 +27,7 @@
 
 It also offers wrappers around C<sendfile> (Solaris, Linux, HP-UX and
 FreeBSD, with emulation on other platforms) and C<readahead> (Linux, with
-emulation elsewhere>).
+emulation elsewhere).
 
 The goal is to enable you to write fully non-blocking programs. For
 example, in a game server, you would not want to freeze for a few seconds
@@ -106,13 +106,18 @@
 called once after C<want_poll>. To put it differently, C<want_poll> and
 C<done_poll> are invoked in pairs: after C<want_poll> you have to call
 C<eio_poll ()> until either C<eio_poll> indicates that everything has been
-handled or C<done_poll> has been called, which signals the same.
+handled or C<done_poll> has been called, which signals the same - only one
+method is needed.
 
 Note that C<eio_poll> might return after C<done_poll> and C<want_poll>
 have been called again, so watch out for races in your code.
 
+It is quite common to have an empty C<done_call> callback and only use
+the return value from C<eio_poll>, or, when C<eio_poll> is configured to
+handle all outstanding replies, it's enough to call C<eio_poll> once.
+
 As with C<want_poll>, this callback is called while locks are being held,
-so you I<must not call any libeio functions form within this callback>.
+so you I<must not call any libeio functions from within this callback>.
 
 =item int eio_poll ()
 
@@ -178,7 +183,7 @@
 
     ev_idle_init (&repeat_watcher, repeat);
     ev_async_init (&ready_watcher, ready);
-    ev_async_start (loop &watcher);
+    ev_async_start (loop, &watcher);
 
     eio_init (want_poll, 0);
   }
@@ -235,8 +240,8 @@
 
 =back
 
-Memmbers not explicitly described as accessible must not be
-accessed. Specifically, there is no gurantee that any members will still
+Members not explicitly described as accessible must not be
+accessed. Specifically, there is no guarantee that any members will still
 have the value they had when the request was submitted.
 
 The return value of the callback is normally C<0>, which tells libeio to
@@ -292,21 +297,7 @@
 executing it might still continue to execute, and in other cases it might
 still take a while till the request is cancelled.
 
-Even if cancelled, the finish callback will still be invoked - the
-callbacks of all cancellable requests need to check whether the request
-has been cancelled by calling C<EIO_CANCELLED (req)>:
-
-  static int
-  my_eio_cb (eio_req *req)
-  {
-    if (EIO_CANCELLED (req))
-      return 0;
-  }
-
-In addition, cancelled requests will I<either> have C<< req->result >>
-set to C<-1> and C<errno> to C<ECANCELED>, or I<otherwise> they were
-successfully executed, despite being cancelled (e.g. when they have
-already been executed at the time they were cancelled).
+When cancelled, the finish callback will not be invoked.
 
 C<EIO_CANCELLED> is still true for requests that have successfully
 executed, as long as C<eio_cancel> was called on them at some point.
@@ -632,7 +623,7 @@
 
 =item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
 
-Reads (C<flags == 0>) or modifies (C<flags == EIO_MT_MODIFY) the given
+Reads (C<flags == 0>) or modifies (C<flags == EIO_MT_MODIFY>) the given
 memory area, page-wise, that is, it reads (or reads and writes back) the
 first octet of every page that spans the memory area.
 
@@ -766,7 +757,7 @@
 =item 3) open callback adds more requests
 
 In the open callback, if the open was not successful, copy C<<
-req->errorno >> to C<< grp->errorno >> and set C<< grp->errorno >> to
+req->errorno >> to C<< grp->errorno >> and set C<< grp->result >> to
 C<-1> to signal an error.
 
 Otherwise, malloc some memory or so and issue a read request, adding the
@@ -774,10 +765,10 @@
 
 =item 4) continue issuing requests till finished
 
-In the real callback, check for errors and possibly continue with
+In the read callback, check for errors and possibly continue with
 C<eio_close> or any other eio request in the same way.
 
-As soon as no new requests are added the group request will finish. Make
+As soon as no new requests are added, the group request will finish. Make
 sure you I<always> set C<< grp->result >> to some sensible value.
 
 =back
@@ -790,8 +781,6 @@
 void eio_grp_limit     (eio_req *grp, int limit);
 
 
-=back
-
 
 =head1 LOW LEVEL REQUEST API
 
@@ -928,10 +917,8 @@
 requests, you might want to increase this.
 
 If this symbol is undefined (the default) then libeio will use its default
-stack size (C<sizeof (void *) * 4096> currently). If it is defined, but
-C<0>, then the default operating system stack size will be used. In all
-other cases, the value must be an expression that evaluates to the desired
-stack size.
+stack size (C<sizeof (void *) * 4096> currently). In all other cases, the
+value must be an expression that evaluates to the desired stack size.
 
 =back