diff --git a/API.md b/API.md
index caf45e3..5e72911 100644
--- a/API.md
+++ b/API.md
@@ -29,7 +29,8 @@ the wall clock changes, either via NTP or user input.
 /*
  * Callback example, arg comes from the watcher's *_init() function,
  * w->fd holds the file descriptor or socket, and events is set by
- * libuEv to indicate status: UEV_HUP, UEV_READ and/or UEV_WRITE
+ * libuEv to indicate status: UEV_READ and/or UEV_WRITE with any of
+ * the optional UEV_HUP, UEV_RDHUP, or UEV_PRI for urgent read data.
  */
 void callback       (uev_t *w, void *arg, int events);
 
@@ -38,10 +39,9 @@ int uev_init        (uev_ctx_t *ctx);
 int uev_exit        (uev_ctx_t *ctx);
 int uev_run         (uev_ctx_t *ctx, int flags);         /* UEV_NONE, UEV_ONCE, and/or UEV_NONBLOCK */
 
-/* I/O watcher:     fd      MUST be non-blocking
- *                  events  can be any combination of: UEV_READ, UEV_WRITE, UEV_PRI,
- *                                                     UEV_HUP,  UEV_RDHUP
- *                                                     UEV_EDGE, UEV_ONESHOT
+/* I/O watcher:     fd      *MUST* be non-blocking!
+ *                  events  combination of the main flags:  UEV_READ, UEV_WRITE,
+ *                                                          UEV_EDGE, UEV_ONESHOT
  */
 int uev_io_init     (uev_ctx_t *ctx, uev_t *w, uev_cb_t *cb, void *arg, int fd, int events);
 int uev_io_set      (uev_t *w, int fd, int events);
diff --git a/src/io.c b/src/io.c
index 6ac95bc..9295c9f 100644
--- a/src/io.c
+++ b/src/io.c
@@ -33,7 +33,7 @@
  * @param cb      I/O callback
  * @param arg     Optional callback argument
  * @param fd      File descriptor to watch, or -1 to register an empty watcher
- * @param events  Requested events to watch for, a mask of %UEV_READ, %UEV_WRITE and %UEV_PRI
+ * @param events  Events to watch for: %UEV_READ, %UEV_WRITE, %UEV_EDGE, %UEV_ONESHOW
  *
  * @return POSIX OK(0) or non-zero with @param errno set on error.
  */
diff --git a/src/uev.h b/src/uev.h
index e214ff7..db86844 100644
--- a/src/uev.h
+++ b/src/uev.h
@@ -61,7 +61,11 @@ typedef struct uev {
 	uev_ctx_t      *ctx;
 } uev_t;
 
-/* Generic callback for watchers */
+/*
+ * Generic callback for watchers, @events holds %UEV_READ and/or %UEV_WRITE
+ * with optional %UEV_PRI (priority data available to read) and any of the
+ * %UEV_HUP and/or %UEV_RDHUP, which may be used to signal hang-up events.
+ */
 typedef void (uev_cb_t)(uev_t *w, void *arg, int events);
 
 /* Public interface */