From 67d3f31aa98e6d36af740c504859a4564be9594f Mon Sep 17 00:00:00 2001
From: Bert Belder <bertbelder@gmail.com>
Date: Fri, 1 Dec 2017 22:03:06 +0100
Subject: [PATCH 1/3] doc: extend readme

---
 doc/README.md | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/doc/README.md b/doc/README.md
index 5465b12..f2a42af 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -9,20 +9,30 @@ Linux API and as closely as possible.
 
 Unlike Linux, OS X, and many other operating systems, Windows doesn't
 have a good API for receiving socket state notifications. It only
-supports the `select` and `WSAPoll` APIs, but they suffer from
-well-understood scalability issues. Using I/O completion ports isn't
-always practical when software is designed to be cross-platform.
+supports the `select` and `WSAPoll` APIs, but they
+[don't scale](https://daniel.haxx.se/docs/poll-vs-select.html)
+and suffer from
+[other issues](https://daniel.haxx.se/blog/2012/10/10/wsapoll-is-broken/).
+
+Using I/O completion ports isn't always practical when software is
+designed to be cross-platform. Wepoll offers an alternative that is
+much closer to a drop-in replacement for software that was designed
+to run on Linux.
 
 ## Features
 
-* poll 100000s of sockets, efficiently
-* fully thread safe, multiple threads can poll the same epoll instance
+* can poll 100000s of sockets efficiently
+* fully thread safe
+* multiple threads can poll the same epoll port
 * sockets can be added to multiple epoll sets
+* polling for `EPOLLIN`, `EPOLLOUT`, `EPOLLPRI`, `EPOLLRDHUP`,
+  `EPOLLHUP`, and `EPOLLERR` events
+* `EPOLLONESTHOT` flag
 
 ## Limitations
 
-* only works on sockets (pipes, TTYs not supported)
-* the EPOLLEXCLUSIVE flag isn't supported
+* only works with sockets
+* some modes not suported: `EPOLLET`, `EPOLLEXCLUSIVE`
 
 ## How to use
 
@@ -33,8 +43,9 @@ project, and include the header wherever needed.
 ## Compatibility
 
 * Requires Windows 7 or higher.
-* Can be compiled with recent versions of MSVC and clang.
-  GCC (mingw) should work, but is untested.
+* Can be compiled with recent versions of MSVC and Clang.
+* GCC (mingw) should work (but is untested).
+
 
 ## Compatibility notes
 

From 59b4e444bc4237075902983d13342682f0c60e88 Mon Sep 17 00:00:00 2001
From: Bert Belder <bertbelder@gmail.com>
Date: Fri, 1 Dec 2017 22:06:04 +0100
Subject: [PATCH 2/3] doc: add beginnings of API documentation

---
 doc/README.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 60 insertions(+), 2 deletions(-)

diff --git a/doc/README.md b/doc/README.md
index f2a42af..26f7fba 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -46,7 +46,65 @@ project, and include the header wherever needed.
 * Can be compiled with recent versions of MSVC and Clang.
 * GCC (mingw) should work (but is untested).
 
+## API notes
 
-## Compatibility notes
+### General
+
+* The epoll port is a `HANDLE`, not a file descriptor.
+* All functions set both `errno` and `GetLastError()` on failure.
+
+### epoll_create/epoll_create1
+
+```c
+HANDLE epoll_create(int size);
+HANDLE epoll_create1(int flags);
+```
+
+* Create a new epoll instance (port).
+* `size` is ignored but most be nonzero.
+* `flags` must be zero as there are no supported flags.
+* Returns `INVALID_HANDLE_VALUE` on failure.
+* [man page](http://man7.org/linux/man-pages/man2/epoll_create.2.html)
+
+### epoll_close
+
+```c
+int epoll_close(HANDLE ephnd);
+```
+
+* Close an epoll port.
+* do not attempt to close the epoll port with Windows' `close`,
+  `CloseHandle` or `closesocket` functions.
+
+### epoll_ctl
+
+```c
+int epoll_ctl(HANDLE ephnd,
+              int op,
+              SOCKET sock,
+              struct epoll_event* event);
+```
+
+* Control which socket events are monitored by an epoll port.
+* `ephnd` must be a HANDLE created by `epoll_create` or `epoll_create1`.
+* `op` must be one of `EPOLL_CTL_ADD`, `EPOLL_CTL_MOD`, `EPOLL_CTL_DEL`.
+* TODO: expand
+* [man page](http://man7.org/linux/man-pages/man2/epoll_ctl.2.html)
+
+### epoll_wait
+
+```c
+int epoll_wait(HANDLE ephnd,
+               struct epoll_event* events,
+               int maxevents,
+               int timeout);
+```
+
+* Receive socket events from an epoll port.
+* Returns
+  - -1 on failure
+  - 0 when a timeout occurs
+  - \>0 the number of evens received
+* TODO: expand
+* [man page](http://man7.org/linux/man-pages/man2/epoll_wait.2.html)
 
-**TODO**

From 4dbec23a7be51bd8c89df14a65c77c5e7df87e0a Mon Sep 17 00:00:00 2001
From: Bert Belder <bertbelder@gmail.com>
Date: Fri, 1 Dec 2017 22:07:36 +0100
Subject: [PATCH 3/3] doc: add project name and blurb to license

---
 LICENSE | 1 +
 1 file changed, 1 insertion(+)

diff --git a/LICENSE b/LICENSE
index 5dc1781..555d45b 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,3 +1,4 @@
+wepoll - epoll for Windows
 Copyright 2012-2017, Bert Belder. All rights reserved.
 
 The red-black tree implementation: