From 3b31079a1c301e2035fbb58dd391a3d686623565 Mon Sep 17 00:00:00 2001
From: Joachim Nilsson <troglobit@gmail.com>
Date: Sun, 29 Mar 2015 09:31:14 +0200
Subject: [PATCH] README: Refactor API section in an attempt to make it more
 accessible.

Signed-off-by: Joachim Nilsson <troglobit@gmail.com>
---
 README.md | 60 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 44 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 1368182..b405da4 100644
--- a/README.md
+++ b/README.md
@@ -95,25 +95,47 @@ events: I/O (files, sockets, message queues, etc.), timers, and signals.
     int uev_signal_stop (uev_t *w);                          /* Stop signal watcher */
 ```
 
-To be able to set up callbacks to events the developer first need to
-create an *event context*, achieved by calling `uev_init()` with a
-pointer to a local `uev_ctx_t` variable.
+To monitor events the developer first creates an *event context*, this
+is achieved by calling `uev_init()` with a pointer to a (thread) local
+`uev_ctx_t` variable.
 
-Events are monitored by watchers in [libuEv].  A watcher is nothing more
-than a mechnism that polls a file descriptor.  Register a watcher with a
-callback to the event context by passing the `uev_ctx_t` variable, along
-with an `uev_t` variable to each event's `_init()` function.
+```C
+    uev_ctx_t ctx;
 
-When all watchers are registered call the event loop with `uev_run()`
-and the argument to the event context.  The `flags` parameter is slightly
-mysterious, but can be used to integrate [libuEv] into another event loop.
-With `flags` set to `UEV_ONCE` the event loop returns after having
-served the first event.  If `flags` is set to `UEV_ONCE | UEV_NONBLOCK`
-the event loop returns immediately if no event is available.
+    uev_init(&ctx);
+```
 
-In the case of errors, stream close, or peer shutdown libuEv handles
-much internally, but also lets the callback run.  This is useful for
-stateful connections to be able to detect EOF.
+Then, for each event to be monitored, a *watcher* is registered with the
+event context.  The watcher, an `uev_t`, is initialized with the proper
+file descriptor to monitor, and an event callback function, by calling
+the event type's `_init()` function with the `uev_ctx_t` context.
+
+```C
+    void cleanup_exit(uev_ctx_t *ctx, uev_t *w, void *arg, int events)
+    {
+        /* Graceful exit, with optional cleanup ... */
+        uev_exit(ctx);
+    }
+    
+    uev_t termw;
+
+    uev_signal_init(&ctx, &term, cleanup_exit, NULL, SIGTERM);
+```
+
+When all watchers are registered, call the *event loop* with `uev_run()`
+and the argument to the event context.  The `flags` parameter can be
+used to integrate [libuEv] into another event loop.  With `flags` set to
+`UEV_ONCE` the event loop returns after having served the first event.
+If `flags` is set to `UEV_ONCE | UEV_NONBLOCK` the event loop returns
+immediately if no event is available.
+
+```C
+    uev_run(&ctx, UEV_NONE);
+```
+
+In case of errors, stream close, or peer shutdown, libuEv handles much
+internally, but also lets the callback run.  This is useful for stateful
+connections to be able to detect EOF.
 
 Summary:
 
@@ -271,3 +293,9 @@ used for inspiration is the very small [Picoev][9] by [Oku Kazuho].
 [Dave Zarzycki, Apple]: http://www.youtube.com/watch?v=cD_s6Fjdri8
 
 [libuEv] is developed and maintained by [Joachim Nilsson]
+
+<!--
+  -- Local Variables:
+  --  mode: markdown
+  -- End:
+  -->