Merge branch 'doxygen' into patches-2.0

27 files changed, 1135 insertions, 622 deletions

diff --git a/Doxyfile b/Doxyfile
index 3fc853e5..5d3865e7 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -45,6 +45,15 @@ OPTIMIZE_OUTPUT_FOR_C  = YES
 
 SORT_BRIEF_DOCS        = YES
 
+# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag 
+# can be used to strip a user-defined part of the path. Stripping is 
+# only done if one of the specified strings matches the left-hand part of 
+# the path. The tag can be used to show relative paths in the file list. 
+# If left blank the directory from which doxygen is run is used as the 
+# path to strip.
+
+STRIP_FROM_PATH        = include/
+
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
@@ -54,21 +63,25 @@ SORT_BRIEF_DOCS        = YES
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = event.h evdns.h evhttp.h evrpc.h \
-		       include/event2/event.h include/event2/event_struct.h \
-		       include/event2/event_compat.h \
-		       include/event2/buffer_compat.h \
-		       include/event2/buffer.h include/event2/thread.h \
-		       include/event2/tag.h include/event2/bufferevent.h \
-		       include/event2/bufferevent_struct.h \
-		       include/event2/bufferevent_compat.h \
-		       include/event2/util.h \
-		       include/event2/rpc.h include/event2/rpc_struct.h \
-		       include/event2/rpc_compat.h \
-		       include/event2/dns.h include/event2/dns_struct.h \
-		       include/event2/dns_compat.h \
-		       include/event2/http.h include/event2/http_struct.h \
-		       include/event2/http_compat.h
+INPUT                  = \
+        include/event2/buffer.h \
+        include/event2/buffer_compat.h \
+        include/event2/bufferevent.h \
+        include/event2/bufferevent_compat.h \
+        include/event2/bufferevent_ssl.h \
+        include/event2/dns.h \
+        include/event2/dns_compat.h \
+        include/event2/event.h \
+        include/event2/event_compat.h \
+        include/event2/http.h \
+        include/event2/http_compat.h \
+        include/event2/listener.h \
+        include/event2/rpc.h \
+        include/event2/rpc_compat.h \
+        include/event2/tag.h \
+        include/event2/tag_compat.h \
+        include/event2/thread.h \
+        include/event2/util.h
 
 #---------------------------------------------------------------------------
 # configuration options related to the HTML output
@@ -140,7 +153,7 @@ PDF_HYPERLINKS         = NO
 # plain latex in the generated Makefile. Set this option to YES to get a 
 # higher quality PDF documentation.
 
-USE_PDFLATEX           = NO
+USE_PDFLATEX           = YES
 
 # If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. 
 # command to the generated LaTeX files. This will instruct LaTeX to keep 
@@ -162,7 +175,7 @@ LATEX_HIDE_INDICES     = NO
 # If the GENERATE_MAN tag is set to YES (the default) Doxygen will 
 # generate man pages
 
-GENERATE_MAN           = YES
+GENERATE_MAN           = NO
 
 # The MAN_EXTENSION tag determines the extension that is added to 
 # the generated man pages (default is the subroutine's section .3)
@@ -226,7 +239,7 @@ INCLUDE_FILE_PATTERNS  =
 # undefined via #undef or recursively expanded use the := operator 
 # instead of the = operator.
 
-PREDEFINED             = TAILQ_ENTRY RB_ENTRY _EVENT_DEFINED_TQENTRY
+PREDEFINED             = TAILQ_ENTRY RB_ENTRY _EVENT_DEFINED_TQENTRY _EVENT_IN_DOXYGEN
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 
 # this tag can be used to specify a list of macro names that should be expanded. 
diff --git a/evdns.h b/evdns.h
index 0f50c4ad..f5aa91c4 100644
--- a/evdns.h
+++ b/evdns.h
@@ -27,6 +27,16 @@
 #ifndef _EVDNS_H_
 #define _EVDNS_H_
 
+/** @file evdns.h
+
+  A dns subsystem for Libevent.
+
+  The <evdns.h> header is deprecated in Libevent 2.0 and later; please
+  use <event2/evdns.h> instead.  Depending on what functionality you
+  need, you may also want to include more of the other event2/*.h
+  headers.
+ */
+
 #include <event.h>
 #include <event2/dns.h>
 #include <event2/dns_compat.h>
diff --git a/event.h b/event.h
index e75e0756..60a003be 100644
--- a/event.h
+++ b/event.h
@@ -27,135 +27,14 @@
 #ifndef _EVENT_H_
 #define _EVENT_H_
 
-/** @mainpage
+/** @file event.h
 
-  @section intro Introduction
-
-  libevent is an event notification library for developing scalable network
-  servers.  The libevent API provides a mechanism to execute a callback
-  function when a specific event occurs on a file descriptor or after a
-  timeout has been reached. Furthermore, libevent also support callbacks due
-  to signals or regular timeouts.
-
-  libevent is meant to replace the event loop found in event driven network
-  servers. An application just needs to call event_dispatch() and then add or
-  remove events dynamically without having to change the event loop.
-
-  Currently, libevent supports /dev/poll, kqueue(2), select(2), poll(2) and
-  epoll(4). It also has experimental support for real-time signals. The
-  internal event mechanism is completely independent of the exposed event API,
-  and a simple update of libevent can provide new functionality without having
-  to redesign the applications. As a result, Libevent allows for portable
-  application development and provides the most scalable event notification
-  mechanism available on an operating system. Libevent can also be used for
-  multi-threaded applications; see Steven Grimm's explanation. Libevent should
-  compile on Linux, *BSD, Mac OS X, Solaris and Windows.
-
-  @section usage Standard usage
-
-  Every program that uses libevent must include the <event.h> header, and pass
-  the -levent flag to the linker.  Before using any of the functions in the
-  library, you must call event_init() or event_base_new() to perform one-time
-  initialization of the libevent library.
-
-  @section event Event notification
-
-  For each file descriptor that you wish to monitor, you must declare an event
-  structure and call event_set() to initialize the members of the structure.
-  To enable notification, you add the structure to the list of monitored
-  events by calling event_add().  The event structure must remain allocated as
-  long as it is active, so it should be allocated on the heap. Finally, you
-  call event_dispatch() to loop and dispatch events.
-
-  @section bufferevent I/O Buffers
-
-  libevent provides an abstraction on top of the regular event callbacks. This
-  abstraction is called a buffered event. A buffered event provides input and
-  output buffers that get filled and drained automatically. The user of a
-  buffered event no longer deals directly with the I/O, but instead is reading
-  from input and writing to output buffers.
-
-  Once initialized via bufferevent_new(), the bufferevent structure can be
-  used repeatedly with bufferevent_enable() and bufferevent_disable().
-  Instead of reading and writing directly to a socket, you would call
-  bufferevent_read() and bufferevent_write().
-
-  When read enabled the bufferevent will try to read from the file descriptor
-  and call the read callback. The write callback is executed whenever the
-  output buffer is drained below the write low watermark, which is 0 by
-  default.
-
-  @section timers Timers
-
-  libevent can also be used to create timers that invoke a callback after a
-  certain amount of time has expired. The evtimer_set() function prepares an
-  event struct to be used as a timer. To activate the timer, call
-  evtimer_add(). Timers can be deactivated by calling evtimer_del().
-
-  @section timeouts Timeouts
-
-  In addition to simple timers, libevent can assign timeout events to file
-  descriptors that are triggered whenever a certain amount of time has passed
-  with no activity on a file descriptor.  The timeout_set() function
-  initializes an event struct for use as a timeout. Once initialized, the
-  event must be activated by using timeout_add().  To cancel the timeout, call
-  timeout_del().
-
-  @section evdns Asynchronous DNS resolution
-
-  libevent provides an asynchronous DNS resolver that should be used instead
-  of the standard DNS resolver functions.  These functions can be imported by
-  including the <evdns.h> header in your program. Before using any of the
-  resolver functions, you must call evdns_init() to initialize the library. To
-  convert a hostname to an IP address, you call the evdns_resolve_ipv4()
-  function.  To perform a reverse lookup, you would call the
-  evdns_resolve_reverse() function.  All of these functions use callbacks to
-  avoid blocking while the lookup is performed.
-
-  @section evhttp Event-driven HTTP servers
-
-  libevent provides a very simple event-driven HTTP server that can be
-  embedded in your program and used to service HTTP requests.
-
-  To use this capability, you need to include the <evhttp.h> header in your
-  program.  You create the server by calling evhttp_new(). Add addresses and
-  ports to listen on with evhttp_bind_socket(). You then register one or more
-  callbacks to handle incoming requests.  Each URI can be assigned a callback
-  via the evhttp_set_cb() function.  A generic callback function can also be
-  registered via evhttp_set_gencb(); this callback will be invoked if no other
-  callbacks have been registered for a given URI.
-
-  @section evrpc A framework for RPC servers and clients
-
-  libevent provides a framework for creating RPC servers and clients.  It
-  takes care of marshaling and unmarshaling all data structures.
-
-  @section api API Reference
-
-  To browse the complete documentation of the libevent API, click on any of
-  the following links.
-
-  event2/event.h
-  The primary libevent header
-
-  event2/buffer.h
-  Buffer management for network reading and writing
-
-  event2/dns.h
-  Asynchronous DNS resolution
-
-  event2/http.h
-  An embedded libevent-based HTTP server
-
-  evrpc.h
-  A framework for creating RPC servers and clients
-
- */
-
-/** @file libevent/event.h
-
-  A library for writing event-driven network servers
+  A library for writing event-driven network servers.
 
+  The <event.h> header is deprecated in Libevent 2.0 and later; please
+  use <event2/event.h> instead.  Depending on what functionality you
+  need, you may also want to include more of the other event2/
+  headers.
  */
 
 #ifdef __cplusplus
diff --git a/evhttp.h b/evhttp.h
index 99bc4da5..1707aa7f 100644
--- a/evhttp.h
+++ b/evhttp.h
@@ -27,6 +27,16 @@
 #ifndef _EVHTTP_H_
 #define _EVHTTP_H_
 
+/** @file evhttp.h
+
+  An http implementation subsystem for Libevent.
+
+  The <evhttp.h> header is deprecated in Libevent 2.0 and later; please
+  use <event2/http.h> instead.  Depending on what functionality you
+  need, you may also want to include more of the other event2/*.h
+  headers.
+ */
+
 #include <event.h>
 #include <event2/http.h>
 #include <event2/http_struct.h>
diff --git a/evrpc.h b/evrpc.h
index 92147d8d..a9f85d7b 100644
--- a/evrpc.h
+++ b/evrpc.h
@@ -27,6 +27,16 @@
 #ifndef _EVRPC_H_
 #define _EVRPC_H_
 
+/** @file evrpc.h
+
+  An RPC system for Libevent.
+
+  The <evrpc.h> header is deprecated in Libevent 2.0 and later; please
+  use <event2/rpc.h> instead.  Depending on what functionality you
+  need, you may also want to include more of the other event2/*.h
+  headers.
+ */
+
 #include <event.h>
 #include <event2/rpc.h>
 #include <event2/rpc_struct.h>
diff --git a/evutil.h b/evutil.h
index cb3754a7..efa2b424 100644
--- a/evutil.h
+++ b/evutil.h
@@ -26,6 +26,14 @@
 #ifndef _EVUTIL_H_
 #define _EVUTIL_H_
 
+/** @file evutil.h
+
+  Utility and compatibility functions for Libevent.
+
+  The <evutil.h> header is deprecated in Libevent 2.0 and later; please
+  use <event2/util.h> instead.
+*/
+
 #include <event2/util.h>
 
 #endif /* _EVUTIL_H_ */
diff --git a/include/event2/buffer.h b/include/event2/buffer.h
index d6538071..19f6f90a 100644
--- a/include/event2/buffer.h
+++ b/include/event2/buffer.h
@@ -26,20 +26,22 @@
 #ifndef _EVENT2_BUFFER_H_
 #define _EVENT2_BUFFER_H_
 
-/** @file buffer.h
+/** @file event2/buffer.h
 
   Functions for buffering data for network sending or receiving.
 
   An evbuffer can be used for preparing data before sending it to
   the network or conversely for reading data from the network.
   Evbuffers try to avoid memory copies as much as possible.  As a
-  result evbuffers can be used to pass data around without actually
+  result, evbuffers can be used to pass data around without actually
   incurring the overhead of copying the data.
 
   A new evbuffer can be allocated with evbuffer_new(), and can be
-  freed with evbuffer_free().
+  freed with evbuffer_free().  Most users will be using evbuffers via
+  the bufferevent interface.  To access a bufferevent's evbuffers, use
+  bufferevent_get_input() and bufferevent_get_output().
 
-  There are several guide lines for using evbuffers.
+  There are several guidelines for using evbuffers.
 
   - if you already know how much data you are going to add as a result
     of calling evbuffer_add() multiple times, it makes sense to use
@@ -53,12 +55,21 @@
     if you use them, you will wind up with fragmented memory in your
 	buffer.
 
-  As the contents of an evbuffer can be stored into multiple different
+  - For high-performance code, you may want to avoid copying data into and out
+    of buffers.  You can skip the copy step by using
+    evbuffer_reserve_space()/evbuffer_commit_space() when writing into a
+    buffer, and evbuffer_peek() when reading.
+
+  In Libevent 2.0 and later, evbuffers are represented using a linked
+  list of memory chunks, with pointers to the first and last chunk in
+  the chain.
+
+  As the contents of an evbuffer can be stored in multiple different
   memory blocks, it cannot be accessed directly.  Instead, evbuffer_pullup()
-  can be used to force a specified number of bytes to be continuous. This
+  can be used to force a specified number of bytes to be contiguous. This
   will cause memory reallocation and memory copies if the data is split
-  across multiple blocks.
-
+  across multiple blocks.  It is more efficient, however, to use
+  evbuffer_peek() if you don't require that the memory to be contiguous.
  */
 
 #ifdef __cplusplus
@@ -75,12 +86,25 @@ extern "C" {
 #endif
 #include <event2/util.h>
 
-struct evbuffer;
+/**
+   An evbuffer is an opaque data type for efficiently buffering data to be
+   sent or received on the network.
+
+   @see event2/event.h for more information
+*/
+struct evbuffer
+#ifdef _EVENT_IN_DOXYGEN
+{}
+#endif
+;
+
+/**
+    Pointer to a position within an evbuffer.
 
-/** Points to a position within an evbuffer. Used when repeatedly searching
-    through a buffer.  Calls to any function that modifies or re-packs the
-    buffer contents may invalidate all evbuffer_ptrs for that buffer.  Do not
-    modify these values except with evbuffer_ptr_set.
+    Used when repeatedly searching through a buffer.  Calling any function
+    that modifies or re-packs the buffer contents may invalidate all
+    evbuffer_ptrs for that buffer.  Do not modify these values except with
+    evbuffer_ptr_set.
  */
 struct evbuffer_ptr {
 	ev_ssize_t pos;
@@ -118,7 +142,6 @@ struct evbuffer_iovec {
  */
 struct evbuffer *evbuffer_new(void);
 
-
 /**
   Deallocate storage for an evbuffer.
 
@@ -153,10 +176,10 @@ void evbuffer_lock(struct evbuffer *buf);
 void evbuffer_unlock(struct evbuffer *buf);
 
 /**
-  Returns the total number of bytes stored in the event buffer
+  Returns the total number of bytes stored in the evbuffer
 
   @param buf pointer to the evbuffer
-  @return the number of bytes stored in the event buffer
+  @return the number of bytes stored in the evbuffer
 */
 size_t evbuffer_get_length(const struct evbuffer *buf);
 
@@ -175,28 +198,28 @@ size_t evbuffer_get_length(const struct evbuffer *buf);
 size_t evbuffer_get_contiguous_space(const struct evbuffer *buf);
 
 /**
-  Expands the available space in an event buffer.
+  Expands the available space in an evbuffer.
 
-  Expands the available space in the event buffer to at least datlen, so that
+  Expands the available space in the evbuffer to at least datlen, so that
   appending datlen additional bytes will not require any new allocations.
 
-  @param buf the event buffer to be expanded
+  @param buf the evbuffer to be expanded
   @param datlen the new minimum length requirement
   @return 0 if successful, or -1 if an error occurred
 */
 int evbuffer_expand(struct evbuffer *buf, size_t datlen);
 
 /**
-   Reserves space in the last chain of an event buffer.
+   Reserves space in the last chain or chains of an evbuffer.
 
-   Makes space available in the last chain of an event buffer that can
+   Makes space available in the last chain or chains of an evbuffer that can
    be arbitrarily written to by a user.  The space does not become
    available for reading until it has been committed with
    evbuffer_commit_space().
 
    The space is made available as one or more extents, represented by
    an initial pointer and a length.  You can force the memory to be
-   available as only one extent.  Allowing more, however, makes the
+   available as only one extent.  Allowing more extents, however, makes the
    function more efficient.
 
    Multiple subsequent calls to this function will make the same space
@@ -208,19 +231,20 @@ int evbuffer_expand(struct evbuffer *buf, size_t datlen);
    NOTE: The code currently does not ever use more than two extents.
    This may change in future versions.
 
-   @param buf the event buffer in which to reserve space.
+   @param buf the evbuffer in which to reserve space.
    @param size how much space to make available, at minimum.  The
       total length of the extents may be greater than the requested
       length.
    @param vec an array of one or more evbuffer_iovec structures to
       hold pointers to the reserved extents of memory.
-   @param n_vec The length of the vec array.  Must be at least 1.
+   @param n_vec The length of the vec array.  Must be at least 1;
+       2 is more efficient.
    @return the number of provided extents, or -1 on error.
-   @see evbuffer_commit_space
+   @see evbuffer_commit_space()
 */
 int
 evbuffer_reserve_space(struct evbuffer *buf, ev_ssize_t size,
-    struct evbuffer_iovec *vec, int n_vecs);
+    struct evbuffer_iovec *vec, int n_vec);
 
 /**
    Commits previously reserved space.
@@ -233,15 +257,15 @@ evbuffer_reserve_space(struct evbuffer *buf, ev_ssize_t size,
    has been added to the buffer since the space was reserved.
 
    If you want to commit less data than you got reserved space for,
-   modify the iov_len pointer of the buffer to a smaller value.  Note
-   that you may have received more space than you requested if it was
-   available!
+   modify the iov_len pointer of the appropriate extent to a smaller
+   value.  Note that you may have received more space than you
+   requested if it was available!
 
-   @param buf the event buffer in which to reserve space.
+   @param buf the evbuffer in which to reserve space.
    @param vec one or two extents returned by evbuffer_reserve_space.
    @param n_vecs the number of extents.
    @return 0 on success, -1 on error
-   @see evbuffer_reserve_space
+   @see evbuffer_reserve_space()
 */
 int evbuffer_commit_space(struct evbuffer *buf,
     struct evbuffer_iovec *vec, int n_vecs);
@@ -249,7 +273,7 @@ int evbuffer_commit_space(struct evbuffer *buf,
 /**
   Append data to the end of an evbuffer.
 
-  @param buf the event buffer to be appended to
+  @param buf the evbuffer to be appended to
   @param data pointer to the beginning of the data buffer
   @param datlen the number of bytes to be copied from the data buffer
   @return 0 on success, -1 on failure.
@@ -258,9 +282,12 @@ int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen);
 
 
 /**
-  Read data from an event buffer and drain the bytes read.
+  Read data from an evbuffer and drain the bytes read.
+
+  If more bytes are requested than are available in the evbuffer, we
+  only extract as many bytes as were available.
 
-  @param buf the event buffer to be read from
+  @param buf the evbuffer to be read from
   @param data the destination buffer to store the result
   @param datlen the maximum size of the destination buffer
   @return the number of bytes read, or -1 if we can't drain the buffer.
@@ -268,22 +295,28 @@ int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen);
 int evbuffer_remove(struct evbuffer *buf, void *data, size_t datlen);
 
 /**
-  Read data from an event buffer, and leave the buffer unchanged.
+  Read data from an evbuffer, and leave the buffer unchanged.
 
-  @param buf the event buffer to be read from
-  @param data the destination buffer to store the result
+  If more bytes are requested than are available in the evbuffer, we
+  only extract as many bytes as were available.
+
+  @param buf the evbuffer to be read from
+  @param data_out the destination buffer to store the result
   @param datlen the maximum size of the destination buffer
   @return the number of bytes read, or -1 if we can't drain the buffer.
  */
 ev_ssize_t evbuffer_copyout(struct evbuffer *buf, void *data_out, size_t datlen);
 
 /**
-  Read data from an event buffer into another event buffer draining
-  the bytes from the src buffer read.  This function avoids memcpy
-  as possible.
+  Read data from an evbuffer into another evbuffer, draining
+  the bytes from the source buffer.  This function avoids copy
+  operations to the extent possible.
 
-  @param src the event buffer to be read from
-  @param dst the destination event buffer to store the result into
+  If more bytes are requested than are available in src, the src
+  buffer is drained completely.
+
+  @param src the evbuffer to be read from
+  @param dst the destination evbuffer to store the result into
   @param datlen the maximum numbers of bytes to transfer
   @return the number of bytes read
  */
@@ -293,7 +326,15 @@ int evbuffer_remove_buffer(struct evbuffer *src, struct evbuffer *dst,
 /** Used to tell evbuffer_readln what kind of line-ending to look for.
  */
 enum evbuffer_eol_style {
-	/** Any sequence of CR and LF characters is acceptable as an EOL. */
+	/** Any sequence of CR and LF characters is acceptable as an
+	 * EOL.
+	 *
+	 * Note that this style can produce ambiguous results: the
+	 * sequence "CRLF" will be treated as a single EOL if it is
+	 * all in the buffer at once, but if you first read a CR from
+	 * the network and later read an LF from the network, it will
+	 * be treated as two EOLs.
+	 */
 	EVBUFFER_EOL_ANY,
 	/** An EOL is an LF, optionally preceded by a CR.  This style is
 	 * most useful for implementing text-based internet protocols. */
@@ -305,7 +346,7 @@ enum evbuffer_eol_style {
 };
 
 /**
- * Read a single line from an event buffer.
+ * Read a single line from an evbuffer.
  *
  * Reads a line terminated by an EOL as determined by the evbuffer_eol_style
  * argument.  Returns a newly allocated nul-terminated string; the caller must
@@ -322,7 +363,7 @@ char *evbuffer_readln(struct evbuffer *buffer, size_t *n_read_out,
     enum evbuffer_eol_style eol_style);
 
 /**
-  Move data from one evbuffer into another evbuffer.
+  Move all data from one evbuffer into another evbuffer.
 
   This is a destructive add.  The data from one buffer moves into
   the other buffer.  However, no unnecessary memory copies occur.
@@ -330,10 +371,17 @@ char *evbuffer_readln(struct evbuffer *buffer, size_t *n_read_out,
   @param outbuf the output buffer
   @param inbuf the input buffer
   @return 0 if successful, or -1 if an error occurred
+
+  @see evbuffer_remove_buffer()
  */
 int evbuffer_add_buffer(struct evbuffer *outbuf, struct evbuffer *inbuf);
 
+/**
+   A cleanup function for a piece of memory added to an evbuffer by
+   reference.
 
+   @see evbuffer_add_reference()
+ */
 typedef void (*evbuffer_ref_cleanup_cb)(const void *data,
     size_t datalen, void *extra);
 
@@ -348,44 +396,48 @@ typedef void (*evbuffer_ref_cleanup_cb)(const void *data,
   @param data the memory to reference
   @param datlen how memory to reference
   @param cleanupfn callback to be invoked when the memory is no longer
-	referenced
-  @param extra optional argument to the cleanup callback
+	referenced by this evbuffer.
+  @param cleanupfn_arg optional argument to the cleanup callback
   @return 0 if successful, or -1 if an error occurred
  */
 int evbuffer_add_reference(struct evbuffer *outbuf,
     const void *data, size_t datlen,
-    evbuffer_ref_cleanup_cb cleanupfn, void *extra);
+    evbuffer_ref_cleanup_cb cleanupfn, void *cleanupfn_arg);
 
 /**
-  Move data from a file into the evbuffer for writing to a socket.
+  Copy data from a file into the evbuffer for writing to a socket.
 
   This function avoids unnecessary data copies between userland and
-  kernel.  Where available, it uses sendfile or splice.
+  kernel.  Where available, it uses sendfile or splice; failing those,
+  it tries to use mmap.
 
   The function owns the resulting file descriptor and will close it
   when finished transferring data.
 
-  The results of using evbuffer_remove() or evbuffer_pullup() are
-  undefined.
+  The results of using evbuffer_remove() or evbuffer_pullup() on
+  evbuffers whose data was added using this function are undefined.
 
   @param outbuf the output buffer
   @param fd the file descriptor
-  @param off the offset from which to read data
+  @param offset the offset from which to read data
   @param length how much data to read
   @return 0 if successful, or -1 if an error occurred
 */
 
-int evbuffer_add_file(struct evbuffer *output, int fd, ev_off_t offset,
+int evbuffer_add_file(struct evbuffer *outbuf, int fd, ev_off_t offset,
     ev_off_t length);
 
 /**
   Append a formatted string to the end of an evbuffer.
 
+  The string is formated as printf.
+
   @param buf the evbuffer that will be appended to
   @param fmt a format string
   @param ... arguments that will be passed to printf(3)
   @return The number of bytes added if successful, or -1 if an error occurred.
 
+  @see evutil_printf(), evbuffer_add_vprintf()
  */
 int evbuffer_add_printf(struct evbuffer *buf, const char *fmt, ...)
 #ifdef __GNUC__
@@ -393,7 +445,6 @@ int evbuffer_add_printf(struct evbuffer *buf, const char *fmt, ...)
 #endif
 ;
 
-
 /**
   Append a va_list formatted string to the end of an evbuffer.
 
@@ -445,7 +496,7 @@ int evbuffer_write_atmost(struct evbuffer *buffer, evutil_socket_t fd,
 /**
   Read from a file descriptor and store the result in an evbuffer.
 
-  @param buf the evbuffer to store the result
+  @param buffer the evbuffer to store the result
   @param fd the file descriptor to read from
   @param howmuch the number of bytes to be read
   @return the number of bytes read, or -1 if an error occurred
@@ -482,6 +533,10 @@ struct evbuffer_ptr evbuffer_search(struct evbuffer *buffer, const char *what, s
  */
 struct evbuffer_ptr evbuffer_search_range(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start, const struct evbuffer_ptr *end);
 
+/**
+   Defines how to adjust an evbuffer_ptr by evbuffer_ptr_set()
+
+   @see evbuffer_ptr_set() */
 enum evbuffer_ptr_how {
 	/** Sets the pointer to the position; can be called on with an
 	    uninitialized evbuffer_ptr. */
@@ -503,7 +558,7 @@ enum evbuffer_ptr_how {
    @returns 0 on success or -1 otherwise
 */
 int
-evbuffer_ptr_set(struct evbuffer *buffer, struct evbuffer_ptr *pos,
+evbuffer_ptr_set(struct evbuffer *buffer, struct evbuffer_ptr *ptr,
     size_t position, enum evbuffer_ptr_how how);
 
 /**
@@ -524,14 +579,6 @@ struct evbuffer_ptr evbuffer_search_eol(struct evbuffer *buffer,
     struct evbuffer_ptr *start, size_t *eol_len_out,
     enum evbuffer_eol_style eol_style);
 
-/** Structure passed to an evbuffer callback */
-struct evbuffer_cb_info {
-	/** The size of */
-	size_t orig_size;
-	size_t n_added;
-	size_t n_deleted;
-};
-
 /** Function to peek at data inside an evbuffer without removing it or
     copying it out.
 
@@ -562,6 +609,21 @@ int evbuffer_peek(struct evbuffer *buffer, ev_ssize_t len,
     struct evbuffer_ptr *start_at,
     struct evbuffer_iovec *vec_out, int n_vec);
 
+
+/** Structure passed to an evbuffer_cb_func evbuffer callback
+
+    @see evbuffer_cb_func, evbuffer_add_cb()
+ */
+struct evbuffer_cb_info {
+	/** The number of bytes in this evbuffer when callbacks were last
+	 * invoked. */
+	size_t orig_size;
+	/** The number of bytes added since callbacks were last invoked. */
+	size_t n_added;
+	/** The number of bytes removed since callbacks were last invoked. */
+	size_t n_deleted;
+};
+
 /** Type definition for a callback that is invoked whenever data is added or
     removed from an evbuffer.
 
@@ -617,7 +679,10 @@ int evbuffer_remove_cb_entry(struct evbuffer *buffer,
 int evbuffer_remove_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg);
 
 /** If this flag is not set, then a callback is temporarily disabled, and
- * should not be invoked. */
+ * should not be invoked.
+ *
+ * @see evbuffer_cb_set_flags(), evbuffer_cb_clear_flags()
+ */
 #define EVBUFFER_CB_ENABLED 1
 
 /** Change the flags that are set for a callback on a buffer by adding more.
diff --git a/include/event2/buffer_compat.h b/include/event2/buffer_compat.h
index 6d0a2446..65e1c82d 100644
--- a/include/event2/buffer_compat.h
+++ b/include/event2/buffer_compat.h
@@ -27,7 +27,7 @@
 #ifndef _EVENT2_BUFFER_COMPAT_H_
 #define _EVENT2_BUFFER_COMPAT_H_
 
-/** @file buffer_compat.h
+/** @file event2/buffer_compat.h
 
 	Obsolete and deprecated versions of the functions in buffer.h: provided
 	only for backward compatibility.
diff --git a/include/event2/bufferevent.h b/include/event2/bufferevent.h
index ee84e084..dac988e3 100644
--- a/include/event2/bufferevent.h
+++ b/include/event2/bufferevent.h
@@ -27,27 +27,51 @@
 #ifndef _EVENT2_BUFFEREVENT_H_
 #define _EVENT2_BUFFEREVENT_H_
 
-/** @file bufferevent.h
+/**
+   @file event2/bufferevent.h
 
   Functions for buffering data for network sending or receiving.  Bufferevents
   are higher level than evbuffers: each has an underlying evbuffer for reading
   and one for writing, and callbacks that are invoked under certain
   circumstances.
 
-  Libevent provides an abstraction on top of the regular event callbacks.
-  This abstraction is called a buffered event.	A buffered event provides
-  input and output buffers that get filled and drained automatically.  The
-  user of a buffered event no longer deals directly with the I/O, but
-  instead is reading from input and writing to output buffers.
+  A bufferevent provides input and output buffers that get filled and
+  drained automatically.  The user of a bufferevent no longer deals
+  directly with the I/O, but instead is reading from input and writing
+  to output buffers.
+
+  Once initialized, the bufferevent structure can be used repeatedly
+  with bufferevent_enable() and bufferevent_disable().
+
+  When reading is enabled, the bufferevent will try to read from the
+  file descriptor onto its input buffer, and and call the read callback.
+  When writing is enabled, the bufferevent will try to write data onto its
+  file descriptor when writing is enabled, and call the write callback
+  when the output buffer is sufficiently drained.
+
+  Bufferevents come in several flavors, including:
 
-  Once initialized, the bufferevent structure can be used repeatedly with
-  bufferevent_enable() and bufferevent_disable().
+  <dl>
+    <dt>Socket-based bufferevents</dt>
+      <dd>A bufferevent that reads and writes data onto a network
+          socket. Created with bufferevent_socket_new().</dd>
 
-  When read enabled the bufferevent will try to read from the file descriptor
-  and call the read callback.  The write callback is executed whenever the
-  output buffer is drained below the write low watermark, which is 0 by
-  default.
+    <dt>Paired bufferevents</dt>
+      <dd>A pair of bufferevents that send and receive data to one
+          another without touching the network.  Created with
+          bufferevent_pair_new().</dd>
 
+    <dt>Filtering bufferevents</dt>
+       <dd>A bufferevent that transforms data, and sends or receives it
+          over another underlying bufferevent.  Created with
+          bufferevent_filter_new().</dd>
+
+    <dt>SSL-backed bufferevents</dt>
+      <dd>A bufferevent that uses the openssl library to send and
+          receive data over an encrypted connection. Created with
+	  bufferevent_openssl_socket_new() or
+	  bufferevent_openssl_filter_new().</dd>
+  </dl>
  */
 
 #ifdef __cplusplus
@@ -65,20 +89,36 @@ extern "C" {
 /* For int types. */
 #include <event2/util.h>
 
-/* Just for error reporting - use other constants otherwise */
+/** @name Bufferevent event codes
+
+    These flags are passed as arguments to a bufferevent's event callback.
+
+    @{
+*/
 #define BEV_EVENT_READING	0x01	/**< error encountered while reading */
 #define BEV_EVENT_WRITING	0x02	/**< error encountered while writing */
 #define BEV_EVENT_EOF		0x10	/**< eof file reached */
 #define BEV_EVENT_ERROR		0x20	/**< unrecoverable error encountered */
-#define BEV_EVENT_TIMEOUT	0x40	/**< user specified timeout reached */
+#define BEV_EVENT_TIMEOUT	0x40	/**< user-specified timeout reached */
 #define BEV_EVENT_CONNECTED	0x80	/**< connect operation finished. */
-struct bufferevent;
+/**@}*/
+
+/**
+   An opaque type for handling buffered IO
+
+   @see event2/bufferevent.h
+ */
+struct bufferevent
+#ifdef _EVENT_IN_DOXYGEN
+{}
+#endif
+;
 struct event_base;
 struct evbuffer;
 struct sockaddr;
 
 /**
-   type definition for the read or write callback.
+   A read or write callback for a bufferevent.
 
    The read callback is triggered when new data arrives in the input
    buffer and the amount of readable data exceed the low watermark
@@ -88,14 +128,14 @@ struct sockaddr;
    exhausted or fell below its low watermark.
 
    @param bev the bufferevent that triggered the callback
-   @param ctx the user specified context for this bufferevent
+   @param ctx the user-specified context for this bufferevent
  */
 typedef void (*bufferevent_data_cb)(struct bufferevent *bev, void *ctx);
 
 /**
-   type definition for the error callback of a bufferevent.
+   An event/error callback for a bufferevent.
 
-   The error callback is triggered if either an EOF condition or another
+   The event callback is triggered if either an EOF condition or another
    unrecoverable error was encountered.
 
    @param bev the bufferevent for which the error condition was reached
@@ -104,7 +144,7 @@ typedef void (*bufferevent_data_cb)(struct bufferevent *bev, void *ctx);
 	  and one of the following flags: BEV_EVENT_EOF, BEV_EVENT_ERROR,
 	  BEV_EVENT_TIMEOUT, BEV_EVENT_CONNECTED.
 
-   @param ctx the user specified context for this bufferevent
+   @param ctx the user-specified context for this bufferevent
 */
 typedef void (*bufferevent_event_cb)(struct bufferevent *bev, short what, void *ctx);
 
@@ -136,6 +176,7 @@ enum bufferevent_options {
 	    This file descriptor is not allowed to be a pipe(2).
 	    It is safe to set the fd to -1, so long as you later
 	    set it with bufferevent_setfd or bufferevent_socket_connect().
+  @param options Zero or more BEV_OPT_* flags
   @return a pointer to a newly allocated bufferevent struct, or NULL if an
 	  error occurred
   @see bufferevent_free()
@@ -143,8 +184,10 @@ enum bufferevent_options {
 struct bufferevent *bufferevent_socket_new(struct event_base *base, evutil_socket_t fd, int options);
 
 /**
-   Launch a connect() attempt with a socket.  When the connect succeeds,
-   the eventcb will be invoked with BEV_EVENT_CONNECTED set.
+   Launch a connect() attempt with a socket-based bufferevent.
+
+   When the connect succeeds, the eventcb will be invoked with
+   BEV_EVENT_CONNECTED set.
 
    If the bufferevent does not already have a socket set, we allocate a new
    socket here and make it nonblocking before we begin.
@@ -188,7 +231,7 @@ struct evdns_base;
    may block while it waits for a DNS response.	 This is probably not
    what you want.
  */
-int bufferevent_socket_connect_hostname(struct bufferevent *b,
+int bufferevent_socket_connect_hostname(struct bufferevent *,
     struct evdns_base *, int, const char *, int);
 
 /**
@@ -383,7 +426,7 @@ int bufferevent_disable(struct bufferevent *bufev, short event);
 short bufferevent_get_enabled(struct bufferevent *bufev);
 
 /**
-  Set the read and write timeout for a buffered event.
+  Set the read and write timeout for a bufferevent.
 
   A bufferevent's timeout will fire the first time that the indicated
   amount of time has elapsed since a successful read or write operation,
@@ -460,8 +503,7 @@ enum bufferevent_flush_mode {
 };
 
 /**
-   Triggers the bufferevent to produce more
-   data if possible.
+   Triggers the bufferevent to produce more data if possible.
 
    @param bufev the bufferevent object
    @param iotype either EV_READ or EV_WRITE or both.
@@ -473,9 +515,10 @@ int bufferevent_flush(struct bufferevent *bufev,
     enum bufferevent_flush_mode mode);
 
 /**
-   Support for filtering input and output of bufferevents.
- */
+   @name Filtering support
 
+   @{
+*/
 /**
    Values that filters can return.
  */
@@ -533,6 +576,7 @@ bufferevent_filter_new(struct bufferevent *underlying,
 		       int options,
 		       void (*free_context)(void *),
 		       void *ctx);
+/**@}*/
 
 /**
    Allocate a pair of linked bufferevents.  The bufferevents behave as would
@@ -680,13 +724,16 @@ int bufferevent_add_to_rate_limit_group(struct bufferevent *bev,
 /** Remove 'bev' from its current rate-limit group (if any). */
 int bufferevent_remove_from_rate_limit_group(struct bufferevent *bev);
 
-/*@{*/
 /**
+   @name Rate limit inspection
+
    Return the current read or write bucket size for a bufferevent.
    If it is not configured with a per-bufferevent ratelimit, return
    EV_SSIZE_MAX.  This function does not inspect the group limit, if any.
    Note that it can return a negative value if the bufferevent has been
    made to read or write more than its limit.
+
+   @{
  */
 ev_ssize_t bufferevent_get_read_limit(struct bufferevent *bev);
 ev_ssize_t bufferevent_get_write_limit(struct bufferevent *bev);
@@ -695,11 +742,14 @@ ev_ssize_t bufferevent_get_write_limit(struct bufferevent *bev);
 ev_ssize_t bufferevent_get_max_to_read(struct bufferevent *bev);
 ev_ssize_t bufferevent_get_max_to_write(struct bufferevent *bev);
 
-/*@{*/
 /**
+   @name GrouprRate limit inspection
+
    Return the read or write bucket size for a bufferevent rate limit
    group.  Note that it can return a negative value if bufferevents in
    the group have been made to read or write more than their limits.
+
+   @{
  */
 ev_ssize_t bufferevent_rate_limit_group_get_read_limit(
 	struct bufferevent_rate_limit_group *);
@@ -707,8 +757,9 @@ ev_ssize_t bufferevent_rate_limit_group_get_write_limit(
 	struct bufferevent_rate_limit_group *);
 /*@}*/
 
-/*@{*/
 /**
+   @name Rate limit manipulation
+
    Subtract a number of bytes from a bufferevent's read or write bucket.
    The decrement value can be negative, if you want to manually refill
    the bucket.	If the change puts the bucket above or below zero, the
@@ -717,13 +768,16 @@ ev_ssize_t bufferevent_rate_limit_group_get_write_limit(
    group, if any.
 
    Returns 0 on success, -1 on internal error.
+
+   @{
  */
 int bufferevent_decrement_read_limit(struct bufferevent *bev, ev_ssize_t decr);
 int bufferevent_decrement_write_limit(struct bufferevent *bev, ev_ssize_t decr);
 /*@}*/
 
-/*@{*/
 /**
+   @name Group rate limit manipulation
+
    Subtract a number of bytes from a bufferevent rate-limiting group's
    read or write bucket.  The decrement value can be negative, if you
    want to manually refill the bucket.	If the change puts the bucket
@@ -731,6 +785,8 @@ int bufferevent_decrement_write_limit(struct bufferevent *bev, ev_ssize_t decr);
    suspend reading writing as appropriate.
 
    Returns 0 on success, -1 on internal error.
+
+   @{
  */
 int bufferevent_rate_limit_group_decrement_read(
 	struct bufferevent_rate_limit_group *, ev_ssize_t);
@@ -739,14 +795,20 @@ int bufferevent_rate_limit_group_decrement_write(
 /*@}*/
 
 
-/** Set the variable pointed to by total_read_out to the total number of bytes
+/**
+ * Inspect the total bytes read/written on a group.
+ *
+ * Set the variable pointed to by total_read_out to the total number of bytes
  * ever read on grp, and the variable pointed to by total_written_out to the
  * total number of bytes ever written on grp. */
 void bufferevent_rate_limit_group_get_totals(
     struct bufferevent_rate_limit_group *grp,
     ev_uint64_t *total_read_out, ev_uint64_t *total_written_out);
 
-/** Reset the number of bytes read or written on grp as given by
+/**
+ * Reset the total bytes read/written on a group.
+ *
+ * Reset the number of bytes read or written on grp as given by
  * bufferevent_rate_limit_group_reset_totals(). */
 void
 bufferevent_rate_limit_group_reset_totals(
diff --git a/include/event2/bufferevent_compat.h b/include/event2/bufferevent_compat.h
index 49dc4aef..6064a40f 100644
--- a/include/event2/bufferevent_compat.h
+++ b/include/event2/bufferevent_compat.h
@@ -54,6 +54,10 @@
   If multiple bases are in use, bufferevent_base_set() must be called before
   enabling the bufferevent for the first time.
 
+  @deprecated This function is deprecated because it uses the current
+    event base, and as such can be error prone for multithreaded programs.
+    Use bufferevent_socket_new() instead.
+
   @param fd the file descriptor from which data is read and written to.
 	 This file descriptor is not allowed to be a pipe(2).
   @param readcb callback to invoke when there is data to be read, or NULL if
diff --git a/include/event2/bufferevent_ssl.h b/include/event2/bufferevent_ssl.h
index 03629331..12f00d63 100644
--- a/include/event2/bufferevent_ssl.h
+++ b/include/event2/bufferevent_ssl.h
@@ -26,7 +26,7 @@
 #ifndef _EVENT2_BUFFEREVENT_SSL_H_
 #define _EVENT2_BUFFEREVENT_SSL_H_
 
-/** @file bufferevent_ssl.h
+/** @file event2/bufferevent_ssl.h
 
     OpenSSL support for bufferevents.
  */
@@ -39,15 +39,31 @@
 extern "C" {
 #endif
 
+/* This is what openssl's SSL objects are underneath. */
 struct ssl_st;
 
+/**
+   The state of an SSL object to be used when creating a new
+   SSL bufferevent.
+ */
 enum bufferevent_ssl_state {
 	BUFFEREVENT_SSL_OPEN = 0,
 	BUFFEREVENT_SSL_CONNECTING = 1,
 	BUFFEREVENT_SSL_ACCEPTING = 2
 };
 
-#ifdef _EVENT_HAVE_OPENSSL
+#if defined(_EVENT_HAVE_OPENSSL) || defined(_EVENT_IN_DOXYGEN)
+/**
+   Create a new SSL bufferevent to send its data over another bufferevent.
+
+   @param base An event_base to use to detect reading and writing.  It
+      must also be the base for the underlying bufferevent.
+   @param underlying A socket to use for this SSL
+   @param ssl A SSL* object from openssl.
+   @param state The current state of the SSL connection
+   @param options One or more bufferevent_options
+   @return A new bufferevent on success, or NULL on failure
+*/
 struct bufferevent *
 bufferevent_openssl_filter_new(struct event_base *base,
     struct bufferevent *underlying,
@@ -55,6 +71,16 @@ bufferevent_openssl_filter_new(struct event_base *base,
     enum bufferevent_ssl_state state,
     int options);
 
+/**
+   Create a new SSL bufferevent to send its data over an SSL * on a socket.
+
+   @param base An event_base to use to detect reading and writing
+   @param fd A socket to use for this SSL
+   @param ssl A SSL* object from openssl.
+   @param state The current state of the SSL connection
+   @param options One or more bufferevent_options
+   @return A new bufferevent on success, or NULL on failure.
+*/
 struct bufferevent *
 bufferevent_openssl_socket_new(struct event_base *base,
     evutil_socket_t fd,
@@ -62,11 +88,14 @@ bufferevent_openssl_socket_new(struct event_base *base,
     enum bufferevent_ssl_state state,
     int options);
 
+/** Return the underlying openssl SSL * object for an SSL bufferevent. */
 struct ssl_st *
 bufferevent_openssl_get_ssl(struct bufferevent *bufev);
 
+/** Tells a bufferevent to begin SSL renegotiation. */
 int bufferevent_ssl_renegotiate(struct bufferevent *bev);
 
+/** Return the most recent OpenSSL error reported on an SSL bufferevent. */
 unsigned long bufferevent_get_openssl_error(struct bufferevent *bev);
 
 #endif
diff --git a/include/event2/bufferevent_struct.h b/include/event2/bufferevent_struct.h
index 5626e968..d4a0a067 100644
--- a/include/event2/bufferevent_struct.h
+++ b/include/event2/bufferevent_struct.h
@@ -27,11 +27,14 @@
 #ifndef _EVENT2_BUFFEREVENT_STRUCT_H_
 #define _EVENT2_BUFFEREVENT_STRUCT_H_
 
-/** @file bufferevent_struct.h
+/** @file event2/bufferevent_struct.h
 
   Data structures for bufferevents.  Using these structures may hurt forward
   compatibility with later versions of Libevent: be careful!
 
+  @deprecated Use of bufferevent_struct.h is completely deprecated; these
+    structures are only exposed for backward compatibility with programs
+    written before Libevent 2.0 that used them.
  */
 
 #ifdef __cplusplus
diff --git a/include/event2/dns.h b/include/event2/dns.h
index 3bb6f9eb..722699a5 100644
--- a/include/event2/dns.h
+++ b/include/event2/dns.h
@@ -47,7 +47,7 @@
  * the source verbatim in their source distributions)
  */
 
-/** @file dns.h
+/** @file event2/dns.h
  *
  * Welcome, gentle reader
  *
diff --git a/include/event2/dns_compat.h b/include/event2/dns_compat.h
index 89b06fe6..7424c4d3 100644
--- a/include/event2/dns_compat.h
+++ b/include/event2/dns_compat.h
@@ -27,11 +27,12 @@
 #ifndef _EVENT2_DNS_COMPAT_H_
 #define _EVENT2_DNS_COMPAT_H_
 
-/** @file dns_compat.h
+/** @file event2/dns_compat.h
 
   Potentially non-threadsafe versions of the functions in dns.h: provided
   only for backwards compatibility.
 
+
  */
 
 #ifdef __cplusplus
diff --git a/include/event2/dns_struct.h b/include/event2/dns_struct.h
index c501eb20..0eefd40e 100644
--- a/include/event2/dns_struct.h
+++ b/include/event2/dns_struct.h
@@ -27,7 +27,7 @@
 #ifndef _EVENT2_DNS_STRUCT_H_
 #define _EVENT2_DNS_STRUCT_H_
 
-/** @file dns_struct.h
+/** @file event2/dns_struct.h
 
   Data structures for dns.  Using these structures may hurt forward
   compatibility with later versions of Libevent: be careful!
diff --git a/include/event2/event.h b/include/event2/event.h
index 3850318f..c487f780 100644
--- a/include/event2/event.h
+++ b/include/event2/event.h
@@ -27,10 +27,157 @@
 #ifndef _EVENT2_EVENT_H_
 #define _EVENT2_EVENT_H_
 
+/**
+   @mainpage
+
+  @section intro Introduction
+
+  Libevent is an event notification library for developing scalable network
+  servers.  The Libevent API provides a mechanism to execute a callback
+  function when a specific event occurs on a file descriptor or after a
+  timeout has been reached. Furthermore, Libevent also support callbacks due
+  to signals or regular timeouts.
+
+  Libevent is meant to replace the event loop found in event driven network
+  servers. An application just needs to call event_dispatch() and then add or
+  remove events dynamically without having to change the event loop.
+
+
+  Currently, Libevent supports /dev/poll, kqueue(2), select(2), poll(2),
+  epoll(4), and evports. The internal event mechanism is completely
+  independent of the exposed event API, and a simple update of Libevent can
+  provide new functionality without having to redesign the applications. As a
+  result, Libevent allows for portable application development and provides
+  the most scalable event notification mechanism available on an operating
+  system.  Libevent can also be used for multithreaded programs.  Libevent
+  should compile on Linux, *BSD, Mac OS X, Solaris and, Windows.
+
+  @section usage Standard usage
+
+  Every program that uses Libevent must inclurde the <event2/event.h>
+  header, and pass the -levent flag to the linker.  (You can instead link
+  -levent_core if you only want the main event and buffered IO-based code,
+  and don't want to link any protocol code.)
+
+  @section setup Library setup
+
+  Before you call any other Libevent functions, you need to set up the
+  library.  If you're going to use Libevent from multiple threads in a
+  multithreaded application, you need to initialize thread support --
+  typically by using evthread_use_pthreads() or
+  evthread_use_windows_threads().  See <event2/thread.h> for more
+  information.
+
+  This is also the point where you can replace Libevent's memory
+  management functions with event_set_mem_functions, and enable debug mode
+  with event_enable_debug_mode().
+
+  @section base Creating an event base
+
+  Next, you need to create an event_base structure, using event_base_new()
+  or event_base_new_with_config().  The event_base is responsible for
+  keeping track of which events are "pending" (that is to say, being
+  watched to see if they become active) and which events are "active".
+  Every event is associated with a single event_base.
+
+  @section event Event notification
+
+  For each file descriptor that you wish to monitor, you must create an
+  event structure with event_new().  (You may also declare an event
+  structure and call event_assign() to initialize the members of the
+  structure.)  To enable notification, you add the structure to the list
+  of monitored events by calling event_add().  The event structure must
+  remain allocated as long as it is active, so it should generally be
+  allocated on the heap.
+
+  @section loop Dispaching evets.
+
+  Finally, you call event_base_dispatch() to loop and dispatch events.
+  You can also use event_base_loop() for more fine-grained control.
+
+  Currently, only one thread can be dispatching a given event_base at a
+  time.  If you want to run events in multiple threads at once, you can
+  either have a single event_base whose events add work to a work queue,
+  or you can create multiple event_base objects.
+
+  @section bufferevent I/O Buffers
+
+  Libevent provides a buffered I/O abstraction on top of the regular event
+  callbacks. This abstraction is called a bufferevent. A bufferevent
+  provides input and output buffers that get filled and drained
+  automatically. The user of a buffered event no longer deals directly
+  with the I/O, but instead is reading from input and writing to output
+  buffers.
+
+  Once initialized via bufferevent_socket_new(), the bufferevent structure
+  can be used repeatedly with bufferevent_enable() and
+  bufferevent_disable().  Instead of reading and writing directly to a
+  socket, you would call bufferevent_read() and bufferevent_write().
+
+  When read enabled the bufferevent will try to read from the file descriptor
+  and call the read callback. The write callback is executed whenever the
+  output buffer is drained below the write low watermark, which is 0 by
+  default.
+
+  See <event2/bufferevent*.h> for more information.
+
+  @section timers Timers
+
+  Libevent can also be used to create timers that invoke a callback after a
+  certain amount of time has expired. The evtimer_new() function returns
+  an event struct to use as a timer. To activate the timer, call
+  evtimer_add(). Timers can be deactivated by calling evtimer_del().
+
+  @section evdns Asynchronous DNS resolution
+
+  Libevent provides an asynchronous DNS resolver that should be used instead
+  of the standard DNS resolver functions.  See the <event2/dns.h>
+  functions for more detail.
+
+  @section evhttp Event-driven HTTP servers
+
+  Libevent provides a very simple event-driven HTTP server that can be
+  embedded in your program and used to service HTTP requests.
+
+  To use this capability, you need to include the <event2/http.h> header in your
+  program.  See that header for more information.
+
+  @section evrpc A framework for RPC servers and clients
+
+  Libevent provides a framework for creating RPC servers and clients.  It
+  takes care of marshaling and unmarshaling all data structures.
+
+  @section api API Reference
+
+  To browse the complete documentation of the libevent API, click on any of
+  the following links.
+
+  event2/event.h
+  The primary libevent header
+
+  event2/thread.h
+  Functions for use by multithreaded programs
+
+  event2/buffer.h and event2/bufferevent.h
+  Buffer management for network reading and writing
+
+  event2/util.h
+  Utility functions for portable nonblocking network code
+
+  event2/dns.h
+  Asynchronous DNS resolution
+
+  event2/http.h
+  An embedded libevent-based HTTP server
+
+  event2/rpc.h
+  A framework for creating RPC servers and clients
+
+ */
+
 /** @file event2/event.h
 
   Core functions for waiting for and receiving events, and using event bases.
-
 */
 
 #ifdef __cplusplus
@@ -50,15 +197,109 @@ extern "C" {
 /* For int types. */
 #include <event2/util.h>
 
-struct event_base;
-struct event;
-struct event_config;
+/**
+ * Structure to hold information and state for a Libevent dispatch loop.
+ *
+ * The event_base lies at the center of Libevent; every application will
+ * have one.  It keeps track of all pending and active events, and
+ * notifies your application of the active ones.
+ *
+ * This is an opaque structure; you can allocate one using
+ * event_base_new() or event_base_new_with_config().
+ *
+ * @see event_base_new(), event_base_free(), event_base_loop(),
+ *    event_base_new_with_config()
+ */
+struct event_base
+#ifdef _EVENT_IN_DOXYGEN
+{/*Empty body so that doxygen will generate documentation here.*/}
+#endif
+;
 
-/** Enable some relatively expensive debugging checks in Libevent that would
- * normally be turned off.  Generally, these cause code that would otherwise
- * crash mysteriously to fail earlier with an assertion failure.  Note that
- * this method MUST be called before any events or event_bases have been
- * created.
+/**
+ * @struct event
+ *
+ * Structure to represent a single event.
+ *
+ * An event can have some underlying condition it represents: a socket
+ * becoming readable or writeable (or both), or a signal becoming raised.
+ * (An event that represents no underlying condition is still useful: you
+ * can use one to implement a timer, or to communicate between threads.)
+ *
+ * Generally, you can create events with event_new(), then make them
+ * pending with event_add().  As your event_base runs, it will run the
+ * callbacks of an events whose conditions are triggered.  When you
+ * longer want the event, free it with event_free().
+ *
+ * In more depth:
+ *
+ * An event may be "pending" (one whose condition we are watching),
+ * "active" (one whose condition has triggered and whose callback is about
+ * to run), neither, or both.  Events come into existence via
+ * event_assign() or event_new(), and are then neither active nor pending.
+ *
+ * To make an event pending, pass it to event_add().  When doing so, you
+ * can also set a timeout for the event.
+ *
+ * Events become active during an event_base_loop() call when either their
+ * condition has triggered, or when their timeout has elapsed.  You can
+ * also activate an event manually using event_active().  The even_base
+ * loop will run the callbacks of active events; after it has done so, it
+ * marks them as no longer active.
+ *
+ * You can make an event non-pending by passing it to event_del().  This
+ * also makes the event non-active.
+ *
+ * Events can be "persistent" or "non-persistent".  A non-persistent event
+ * becomes non-pending as soon as it is triggered: thus, it only runs at
+ * most once per call to event_add().  A persistent event remains pending
+ * even when it becomes active: you'll need to event_del() it manually in
+ * order to make it non-pending.  When a persistent event with a timeout
+ * becomes active, its timeout is reset: this means you can use persistent
+ * events to implement periodic timeouts.
+ *
+ * This should be treated as an opaque structure; you should never read or
+ * write any of its fields directly.  For backward compatibility with old
+ * code, it is defined in the event2/event_struct.h header; including this
+ * header may make your code incompatible with other versions of Libevent.
+ *
+ * @see event_new(), event_free(), event_assign(), event_get_assignment(),
+ *    event_add(), event_del(), event_active(), event_pending(),
+ *    event_get_fd(), event_get_base(), event_get_events(),
+ *    event_get_callback(), event_get_callback_arg(),
+ *    event_priority_set()
+ */
+struct event
+#ifdef _EVENT_IN_DOXYGEN
+{/*Empty body so that doxygen will generate documentation here.*/}
+#endif
+;
+
+/**
+ * Configuration for an event_base.
+ *
+ * There are many options that can be used to alter the behavior and
+ * implementation of an event_base.  To avoid having to pass them all in a
+ * complex many-argument constructor, we provide an abstract data type
+ * wrhere you set up configation information before passing it to
+ * event_base_new_with_config().
+ *
+ * @see event_config_new(), event_config_free(), event_base_new_with_config(),
+ *   event_config_avoid_method(), event_config_require_features(),
+ *   event_config_set_flag(), event_config_set_num_cpus_hint()
+ */
+struct event_config
+#ifdef _EVENT_IN_DOXYGEN
+{/*Empty body so that doxygen will generate documentation here.*/}
+#endif
+;
+
+/**
+ * Enable some relatively expensive debugging checks in Libevent that
+ * would normally be turned off.  Generally, these checks cause code that
+ * would otherwise crash mysteriously to fail earlier with an assertion
+ * failure.  Note that this method MUST be called before any events or
+ * event_bases have been created.
  *
  * Debug mode can currently catch the following errors:
  *    An event is re-assigned while it is added
@@ -70,6 +311,8 @@ struct event_config;
  * debug mode, and you find yourself running out of memory, you will need
  * to use event_debug_unassign to explicitly stop tracking events that
  * are no longer considered set-up.
+ *
+ * @see event_debug_unassign()
  */
 void event_enable_debug_mode(void);
 
@@ -79,40 +322,44 @@ void event_enable_debug_mode(void);
  * nothing.
  *
  * This function must only be called on a non-added event.
+ *
+ * @see event_enable_debug_mode()
  */
 void event_debug_unassign(struct event *);
 
 /**
-  Initialize the event API.
-
-  Use event_base_new() to initialize a new event base.
-
-  @see event_base_set(), event_base_free(),
-    event_base_new_with_config()
+ * Create and return a new event_base to use with the rest of Libevent.
+ *
+ * @return a new event_base on success, or NULL on failure.
+ *
+ * @see event_base_free(), event_base_new_with_config()
  */
 struct event_base *event_base_new(void);
 
 /**
-  Reinitialized the event base after a fork
+  Reinitialize the event base after a fork
 
   Some event mechanisms do not survive across fork.   The event base needs
   to be reinitialized with the event_reinit() function.
 
   @param base the event base that needs to be re-initialized
   @return 0 if successful, or -1 if some events could not be re-added.
-  @see event_base_new(), event_init()
+  @see event_base_new()
 */
 int event_reinit(struct event_base *base);
 
 /**
-  Threadsafe event dispatching loop.
+   Event dispatching loop
 
   This loop will run the event base until either there are no more added
   events, or until something calls event_base_loopbreak() or
-  evenet_base_loopexit().
+  event_base_loopexit().
 
-  @param eb the event_base structure returned by event_init()
-  @see event_init(), event_dispatch()
+  @param base the event_base structure returned by event_base_new() or
+     event_base_new_with_config()
+  @return 0 if successful, -1 if an error occurred, or 1 if no events were
+    registered.
+  @see event_base_loop()
  */
 int event_base_dispatch(struct event_base *);
 
@@ -144,10 +391,10 @@ const char **event_get_supported_methods(void);
    The event configuration object can be used to change the behavior of
    an event base.
 
-   @return an event_config object that can be used to store configuration or
-     NULL when an error is encountered.
+   @return an event_config object that can be used to store configuration, or
+     NULL if an error is encountered.
+   @see event_base_new_with_config(), event_config_free(), event_config
 */
-
 struct event_config *event_config_new(void);
 
 /**
@@ -161,28 +408,46 @@ void event_config_free(struct event_config *cfg);
    Enters an event method that should be avoided into the configuration.
 
    This can be used to avoid event mechanisms that do not support certain
-   file descriptor types.  An application can make use of multiple event
-   bases to accommodate incompatible file descriptor types.
+   file descriptor types, or for debugging to avoid certain event
+   mechanisms.  An application can make use of multiple event bases to
+   accommodate incompatible file descriptor types.
 
    @param cfg the event configuration object
-   @param method the event method to avoid
+   @param method the name of the event method to avoid
    @return 0 on success, -1 on failure.
 */
 int event_config_avoid_method(struct event_config *cfg, const char *method);
 
+/**
+   A flag used to describe which features an event_base (must) provide.
+
+   Because of OS limitations, not every Libevent backend supports every
+   possible feature.  You can use this type with
+   event_config_require_features() to tell Libevent to only proceed if your
+   event_base implements a given feature, and you can receive this type from
+   event_base_get_features() to see which features are available.
+*/
 enum event_method_feature {
-    /* Require an event method that allows edge-triggered events with EV_ET. */
+    /** Require an event method that allows edge-triggered events with EV_ET. */
     EV_FEATURE_ET = 0x01,
-    /* Require an event method where having one event triggered among
+    /** Require an event method where having one event triggered among
      * many is [approximately] an O(1) operation. This excludes (for
      * example) select and poll, which are approximately O(N) for N
      * equal to the total number of possible events. */
     EV_FEATURE_O1 = 0x02,
-    /* Require an event method that allows file descriptors as well as
+    /** Require an event method that allows file descriptors as well as
      * sockets. */
     EV_FEATURE_FDS = 0x04
 };
 
+/**
+   A flag passed to event_config_set_flag().
+
+    These flags change the behavior of an allocated event_base.
+
+    @see event_config_set_flag(), event_base_new_with_config(),
+       event_method_feature
+ */
 enum event_base_config_flag {
 	/** Do not allocate a lock for the event base, even if we have
 	    locking set up. */
@@ -190,7 +455,12 @@ enum event_base_config_flag {
 	/** Do not check the EVENT_* environment variables when configuring
 	    an event_base  */
 	EVENT_BASE_FLAG_IGNORE_ENV = 0x02,
-	/** Windows only: enable the IOCP dispatcher at startup */
+	/** Windows only: enable the IOCP dispatcher at startup
+
+	    If this flag is set then bufferevent_socket_new() and
+	    evconn_listener_new() will use IOCP-backed implementations
+	    instead of the usual select-based one on Windows.
+	 */
 	EVENT_BASE_FLAG_STARTUP_IOCP = 0x04,
 	/** Instead of checking the current time every time the event loop is
 	    ready to run timeout callbacks, check after each timeout callback.
@@ -215,7 +485,11 @@ enum event_base_config_flag {
 };
 
 /**
- Return a bitmask of the features implemented by an event base.
+   Return a bitmask of the features implemented by an event base.  This
+   will be a bitwise OR of one or more of the values of
+   event_method_feature
+
+   @see event_method_feature
  */
 int event_base_get_features(const struct event_base *base);
 
@@ -239,11 +513,16 @@ int event_base_get_features(const struct event_base *base);
    @param feature a bitfield of one or more event_method_feature values.
           Replaces values from previous calls to this function.
    @return 0 on success, -1 on failure.
+   @see event_method_feature, event_base_new_with_config()
 */
 int event_config_require_features(struct event_config *cfg, int feature);
 
-/** Sets one or more flags to configure what parts of the eventual event_base
- * will be initialized, and how they'll work. */
+/**
+ * Sets one or more flags to configure what parts of the eventual event_base
+ * will be initialized, and how they'll work.
+ *
+ * @see event_base_config_flags, event_base_new_with_config()
+ **/
 int event_config_set_flag(struct event_config *cfg, int flag);
 
 /**
@@ -275,19 +554,25 @@ struct event_base *event_base_new_with_config(const struct event_config *);
   Deallocate all memory associated with an event_base, and free the base.
 
   Note that this function will not close any fds or free any memory passed
-  to event_set as the argument to callback.
+  to event_new as the argument to callback.
 
   @param eb an event_base to be freed
  */
 void event_base_free(struct event_base *);
 
+/** @name Log severities
+ */
+/**@{*/
 #define _EVENT_LOG_DEBUG 0
 #define _EVENT_LOG_MSG   1
 #define _EVENT_LOG_WARN  2
 #define _EVENT_LOG_ERR   3
+/**@}*/
 
-/*
+/**
   A callback function used to intercept Libevent's log messages.
+
+  @see event_set_log_callback
  */
 typedef void (*event_log_cb)(int severity, const char *msg);
 /**
@@ -303,6 +588,13 @@ typedef void (*event_log_cb)(int severity, const char *msg);
 void event_set_log_callback(event_log_cb cb);
 
 /**
+   A function to be called if Libevent encounters a fatal internal error.
+
+   @see event_set_fatal_callback
+ */
+typedef void (*event_fatal_cb)(int err);
+
+/**
  Override Libevent's behavior in the event of a fatal internal error.
 
  By default, Libevent will call exit(1) if a programming error makes it
@@ -314,31 +606,34 @@ void event_set_log_callback(event_log_cb cb);
  Libevent will (almost) always log an _EVENT_LOG_ERR message before calling
  this function; look at the last log message to see why Libevent has died.
  */
-typedef void (*event_fatal_cb)(int err);
 void event_set_fatal_callback(event_fatal_cb cb);
 
 /**
   Associate a different event base with an event.
 
+  The event to be associated must not be currently active or pending.
+
   @param eb the event base
   @param ev the event
+  @return 0 on success, -1 on failure.
  */
 int event_base_set(struct event_base *, struct event *);
 
-/**
- event_base_loop() flags
+/** @name Loop flags
+
+    These flags control the behavior of event_base_loop().
  */
-/*@{*/
+/**@{*/
 /** Block until we have an active event, then exit once all active events
  * have had their callbacks run. */
 #define EVLOOP_ONCE	0x01
 /** Do not block: see which events are ready now, run the callbacks
  * of the highest-priority ones, then exit. */
 #define EVLOOP_NONBLOCK	0x02
-/*@}*/
+/**@}*/
 
 /**
-  Handle events (threadsafe version).
+  Wait for events to become active, and run their callbacks.
 
   This is a more flexible version of event_base_dispatch().
 
@@ -347,16 +642,18 @@ int event_base_set(struct event_base *, struct event *);
   evenet_base_loopexit().  You can override this behavior with the 'flags'
   argument.
 
-  @param eb the event_base structure returned by event_init()
+  @param eb the event_base structure returned by event_base_new() or
+     event_base_new_with_config()
   @param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK
   @return 0 if successful, -1 if an error occurred, or 1 if no events were
     registered.
-  @see event_loopexit(), event_base_loop()
+  @see event_base_loopexit(), event_base_dispatch(), EVLOOP_ONCE,
+     EVLOOP_NONBLOCK
   */
 int event_base_loop(struct event_base *, int);
 
 /**
-  Exit the event loop after the specified time (threadsafe variant).
+  Exit the event loop after the specified time
 
   The next event_base_loop() iteration after the given timer expires will
   complete normally (handling all queued events) then exit without
@@ -365,9 +662,10 @@ int event_base_loop(struct event_base *, int);
   Subsequent invocations of event_base_loop() will proceed normally.
 
   @param eb the event_base structure returned by event_init()
-  @param tv the amount of time after which the loop should terminate.
+  @param tv the amount of time after which the loop should terminate,
+    or NULL to exit after running all currently active events.
   @return 0 if successful, or -1 if an error occurred
-  @see event_loopexit()
+  @see event_base_loopbreak()
  */
 int event_base_loopexit(struct event_base *, const struct timeval *);
 
@@ -382,7 +680,7 @@ int event_base_loopexit(struct event_base *, const struct timeval *);
 
   @param eb the event_base structure returned by event_init()
   @return 0 if successful, or -1 if an error occurred
-  @see event_base_loopexit
+  @see event_base_loopexit()
  */
 int event_base_loopbreak(struct event_base *);
 
@@ -395,8 +693,8 @@ int event_base_loopbreak(struct event_base *);
   @param eb the event_base structure returned by event_init()
   @return true if event_base_loopexit() was called on this event base,
     or 0 otherwise
-  @see event_base_loopexit
-  @see event_base_got_break
+  @see event_base_loopexit()
+  @see event_base_got_break()
  */
 int event_base_got_exit(struct event_base *);
 
@@ -409,52 +707,58 @@ int event_base_got_exit(struct event_base *);
   @param eb the event_base structure returned by event_init()
   @return true if event_base_loopbreak() was called on this event base,
     or 0 otherwise
-  @see event_base_loopbreak
-  @see event_base_got_exit
+  @see event_base_loopbreak()
+  @see event_base_got_exit()
  */
 int event_base_got_break(struct event_base *);
 
-/* Flags to pass to event_set(), event_new(), event_assign(),
- * event_pending(), and anything else with an argument of the form
- * "short events" */
+/**
+ * @name event flags
+ *
+ * Flags to pass to event_new(), event_assign(), event_pending(), and
+ * anything else with an argument of the form "short events"
+ */
+/**@{*/
+/** Indicates that a timeout has occurred.  It's not necessary to pass
+ * this flag to event_for new()/event_assign() to get a timeout. */
 #define EV_TIMEOUT	0x01
+/** Wait for a socket or FD to become readable */
 #define EV_READ		0x02
+/** Wait for a socket or FD to become writeable */
 #define EV_WRITE	0x04
+/** Wait for a POSIX signal to be raised*/
 #define EV_SIGNAL	0x08
-/** Persistent event: won't get removed automatically when activated. */
+/**
+ * Persistent event: won't get removed automatically when activated.
+ *
+ * When a persistent event with a timeout becomes activated, its timeout
+ * is reset to 0.
+ */
 #define EV_PERSIST	0x10
 /** Select edge-triggered behavior, if supported by the backend. */
 #define EV_ET       0x20
+/**@}*/
 
 /**
-  Define a timer event.
+   @name evtimer_* macros
 
-  @param ev event struct to be modified
-  @param b an event_base
-  @param cb callback function
-  @param arg argument that will be passed to the callback function
- */
+    Aliases for working with one-shot timer events */
+/**@{*/
 #define evtimer_assign(ev, b, cb, arg) \
 	event_assign((ev), (b), -1, 0, (cb), (arg))
 #define evtimer_new(b, cb, arg)	       event_new((b), -1, 0, (cb), (arg))
-
-/**
-  Add a timer event.
-
-  @param ev the event struct
-  @param tv timeval struct
- */
 #define evtimer_add(ev, tv)		event_add((ev), (tv))
-
-/**
- * Delete a timer event.
- *
- * @param ev the event struct to be disabled
- */
 #define evtimer_del(ev)			event_del(ev)
 #define evtimer_pending(ev, tv)		event_pending((ev), EV_TIMEOUT, (tv))
 #define evtimer_initialized(ev)		event_initialized(ev)
+/**@}*/
+
+/**
+   @name evsignal_* macros
 
+   Aliases for working with signal events
+ */
+/**@{*/
 #define evsignal_add(ev, tv)		event_add((ev), (tv))
 #define evsignal_assign(ev, b, x, cb, arg)			\
 	event_assign((ev), (b), (x), EV_SIGNAL|EV_PERSIST, cb, (arg))
@@ -463,57 +767,117 @@ int event_base_got_break(struct event_base *);
 #define evsignal_del(ev)		event_del(ev)
 #define evsignal_pending(ev, tv)	event_pending((ev), EV_SIGNAL, (tv))
 #define evsignal_initialized(ev)	event_initialized(ev)
+/**@}*/
 
+/**
+   A callback function for an event.
+
+   It receives three arguments:
+
+   @param fd An fd or signal
+   @param events One or more EV_* flags
+   @param arg A user-supplied argument.
+
+   @see event_new()
+ */
 typedef void (*event_callback_fn)(evutil_socket_t, short, void *);
 
 /**
-  Prepare an event structure to be added.
+  Allocate and asssign a new event structure, ready to be added.
+
+  The function event_new() returns a new event that can be used in
+  future calls to event_add() and event_del().  The fd and events
+  arguments determine which conditions will trigger the event; the
+  callback and callback_arg arguments tell Libevent what to do when the
+  event becomes active.
+
+  If events contains one of EV_READ, EV_WRITE, or EV_READ|EV_WRITE, then
+  fd is a file descriptor or socket that should get monitored for
+  readiness to read, readiness to write, or readiness for either operation
+  (respectively).  If events contains EV_SIGNAL, then fd is a signal
+  number to wait for.  If events contains none of those flags, then the
+  event can be triggered only by a timeout or by manual activation with
+  event_active(): In this case, fd must be -1.
+
+  The EV_PERSIST flag can also be passed in the events argument: it makes
+  event_add() persistent until event_del() is called.
+
+  The EV_ET flag is compatible with EV_READ and EV_WRITE, and supported
+  only by certain backends.  It tells Libevent to use edge-triggered
+  events.
+
+  The EV_TIMEOUT flag has no effect here.
+
+  It is okay to have multiple events all listening on the same fds; but
+  they must either all be edge-triggered, or all not be edge triggerd.
+
+  When the event becomes active, the event loop will run the provided
+  callbuck function, with three arguments.  The first will be the provided
+  fd value.  The second will be a bitfield of the events that triggered:
+  EV_READ, EV_WRITE, or EV_SIGNAL.  Here the EV_TIMEOUT flag indicates
+  that a timeout occurred, and EV_ET indicates that an edge-triggered
+  event occurred.  The third event will be the callback_arg pointer that
+  you provide.
+
+  @param base the event base to which the event should be attached.
+  @param fd the file descriptor or signal to be monitored, or -1.
+  @param events desired events to monitor: bitfield of EV_READ, EV_WRITE,
+      EV_SIGNAL, EV_PERSIST, EV_ET.
+  @param callback callback function to be invoked when the event occurs
+  @param callback_arg an argument to be passed to the callback function
 
-  The function event_assign() prepares the event structure ev to be used in
-  future calls to event_add() and event_del().  The event will be prepared to
-  call the function specified by the fn argument with an int argument
-  indicating the file descriptor, a short argument indicating the type of
-  event, and a void * argument given in the arg argument.  The fd indicates
-  the file descriptor that should be monitored for events.  The events can be
-  either EV_READ, EV_WRITE, or both.  Indicating that an application can read
-  or write from the file descriptor respectively without blocking.
+  @return a newly allocated struct event that must later be freed with
+    event_free().
+  @see event_free(), event_add(), event_del(), event_assign()
+ */
+struct event *event_new(struct event_base *, evutil_socket_t, short, event_callback_fn, void *);
+
+
+/**
+  Prepare a new, already-allocated event structure to be added.
 
-  The function fn will be called with the file descriptor that triggered the
-  event and the type of event which will be either EV_TIMEOUT, EV_SIGNAL,
-  EV_READ, or EV_WRITE.  The additional flag EV_PERSIST makes an event_add()
-  persistent until event_del() has been called.
+  The function event_assign() prepares the event structure ev to be used
+  in future calls to event_add() and event_del().  Unlike event_new(), it
+  doesn't allocate memory itself: it requires that you have already
+  allocated a struct event, probably on the heap.  Doing this will
+  typically make your code depend on the size of the event structure, and
+  thereby create incompatibility with future versions of Libevent.
 
-  Note that using event_assign() request that you have already allocated the
-  event struct.  Doing so will often require your code to depend on the size
-  of the structure, and will create possible incompatibility with future
-  versions of Libevent.  If this seems like a bad idea to you, use event_new()
-  and event_free() instead.
+  The easiest way to avoid this problem is just to use event_new() and
+  event_free() instead.
+
+  A slightly harder way to future-proof your code is to use
+  event_get_struct_event_size() to determine the required size of an event
+  at runtime.
+
+  Note that it is NOT safe to call this function on an event that is
+  active or pending.  Doing so WILL corrupt internal data structures in
+  Libevent, and lead to strange, hard-to-diagnose bugs.  You _can_ use
+  event_assign to change an existing event, but only if it is not active
+  or pending!
+
+  The arguments for this function, and the behavior of the events that it
+  makes, are as for event_new().
 
   @param ev an event struct to be modified
   @param base the event base to which ev should be attached.
   @param fd the file descriptor to be monitored
-  @param event desired events to monitor; can be EV_READ and/or EV_WRITE
-  @param fn callback function to be invoked when the event occurs
-  @param arg an argument to be passed to the callback function
+  @param events desired events to monitor; can be EV_READ and/or EV_WRITE
+  @param callback callback function to be invoked when the event occurs
+  @param callback_arg an argument to be passed to the callback function
 
   @return 0 if success, or -1 on invalid arguments.
 
-  @see event_add(), event_del(), event_once()
-
+  @see event_new(), event_add(), event_del(), event_base_once(),
+    event_get_struct_event_size()
   */
 int event_assign(struct event *, struct event_base *, evutil_socket_t, short, event_callback_fn, void *);
 
 /**
-  Create and allocate a new event structure, ready to be added.
-
-  Arguments are as for event_assign; returns a newly allocated struct event *
-  that must later be deallocated with event_free().
-
- */
-struct event *event_new(struct event_base *, evutil_socket_t, short, event_callback_fn, void *);
-
-/**
    Deallocate a struct event * returned by event_new().
+
+   If the event is pending or active, first make it non-pending and
+   non-active.
  */
 void event_free(struct event *);
 
@@ -521,41 +885,49 @@ void event_free(struct event *);
   Schedule a one-time event
 
   The function event_base_once() is similar to event_set().  However, it
-  schedules a callback to be called exactly once and does not require the
+  schedules a callback to be called exactly once, and does not require the
   caller to prepare an event structure.
 
-  @param base an event_base returned by event_init()
-  @param fd a file descriptor to monitor
-  @param events event(s) to monitor; can be any of EV_TIMEOUT | EV_READ |
-         EV_WRITE
+  Note that in Libevent 2.0 and earlier, if the event is never triggered,
+  the internal memory used to hold it will never be freed.  This may be
+  fixed in a later version of Libevent.
+
+  @param base an event_base
+  @param fd a file descriptor to monitor, or -1 for no fd.
+  @param events event(s) to monitor; can be any of EV_READ |
+         EV_WRITE, or EV_TIMEOUT
   @param callback callback function to be invoked when the event occurs
   @param arg an argument to be passed to the callback function
-  @param timeout the maximum amount of time to wait for the event, or NULL
-         to wait forever
+  @param timeout the maximum amount of time to wait for the event. NULL
+         makes an EV_READ/EV_WRITE event make forever; NULL makes an
+        EV_TIMEOUT event succees immediately.
   @return 0 if successful, or -1 if an error occurred
-  @see event_once()
  */
 int event_base_once(struct event_base *, evutil_socket_t, short, event_callback_fn, void *, const struct timeval *);
 
 /**
-  Add an event to the set of monitored events.
+  Add an event to the set of pending events.
 
   The function event_add() schedules the execution of the ev event when the
-  event specified in event_set() occurs or in at least the time specified in
-  the tv.  If tv is NULL, no timeout occurs and the function will only be
-  called if a matching event occurs on the file descriptor.  The event in the
-  ev argument must be already initialized by event_set() and may not be used
-  in calls to event_set() until it has timed out or been removed with
-  event_del().  If the event in the ev argument already has a scheduled
-  timeout, the old timeout will be replaced by the new one.
+  event specified in event_assign()/event_new() occurs, or when the time
+  specified in timeout has elapesed.  If atimeout is NULL, no timeout
+  occurs and the function will only be
+  called if a matching event occurs.  The event in the
+  ev argument must be already initialized by event_assign() or event_new()
+  and may not be used
+  in calls to event_assign() until it is no longer pending.
+
+  If the event in the ev argument already has a scheduled timeout, calling
+  event_add() replaces the old timeout with the new one, or clears the old
+  timeout if the timeout argument is NULL.
 
   @param ev an event struct initialized via event_set()
   @param timeout the maximum amount of time to wait for the event, or NULL
          to wait forever
   @return 0 if successful, or -1 if an error occurred
-  @see event_del(), event_set()
+  @see event_del(), event_assign(), event_new()
   */
-int event_add(struct event *, const struct timeval *);
+int event_add(struct event *ev, const struct timeval *timeout);
 
 /**
   Remove an event from the set of monitored events.
@@ -574,18 +946,24 @@ int event_del(struct event *);
 /**
   Make an event active.
 
+  You can use this function on a pending or a non-pending event to make it
+  active, so that its callback will be run by event_base_dispatch() or
+  event_base_loop().
+
+  One common use in multithreaded programs is to wake the thread running
+  event_base_loop() from another thread.
+
   @param ev an event to make active.
   @param res a set of flags to pass to the event's callback.
-  @param ncalls
+  @param ncalls an obsolete argument: this is ignored.
  **/
-void event_active(struct event *, int, short);
-
+void event_active(struct event *ev, int res, short ncalls);
 
 /**
   Checks if a specific event is pending or scheduled.
 
   @param ev an event struct previously passed to event_add()
-  @param what the requested event type; any of EV_TIMEOUT|EV_READ|
+  @param events the requested event type; any of EV_TIMEOUT|EV_READ|
          EV_WRITE|EV_SIGNAL
   @param tv if this field is not NULL, and the event has a timeout,
          this field is set to hold the time at which the timeout will
@@ -593,9 +971,8 @@ void event_active(struct event *, int, short);
 
   @return true if the event is pending on any of the events in 'what', (that
   is to say, it has been added), or 0 if the event is not added.
-
  */
-int event_pending(const struct event *, short, struct timeval *);
+int event_pending(const struct event *ev, short events, struct timeval *tv);
 
 
 /**
@@ -616,17 +993,18 @@ int event_pending(const struct event *, short, struct timeval *);
 int event_initialized(const struct event *ev);
 
 /**
-   Get the signal number assigned to an event.
+   Get the signal number assigned to a signal event
 */
 #define event_get_signal(ev) ((int)event_get_fd(ev))
 
 /**
-   Get the socket assigned to an event.
+   Get the socket or signal assigned to an event, or -1 if the event has
+   no socket.
 */
 evutil_socket_t event_get_fd(const struct event *ev);
 
 /**
-   Get the event_base assigned to an event.
+   Get the event_base associated with an event.
 */
 struct event_base *event_get_base(const struct event *ev);
 
@@ -701,20 +1079,37 @@ ev_uint32_t event_get_version_number(void);
  * headers. */
 #define LIBEVENT_VERSION_NUMBER _EVENT_NUMERIC_VERSION
 
+/** Largest number of priorities that Libevent can support. */
 #define EVENT_MAX_PRIORITIES 256
 /**
-  Set the number of different event priorities (threadsafe variant).
-
-  See the description of event_priority_init() for more information.
-
-  @param eb the event_base structure returned by event_init()
+  Set the number of different event priorities
+
+  By default Libevent schedules all active events with the same priority.
+  However, some time it is desirable to process some events with a higher
+  priority than others.  For that reason, Libevent supports strict priority
+  queues.  Active events with a lower priority are always processed before
+  events with a higher priority.
+
+  The number of different priorities can be set initially with the
+  event_base_priority_init() function.  This function should be called
+  before the first call to event_base_dispatch().  The
+  event_priority_set() function can be used to assign a priority to an
+  event.  By default, Libevent assigns the middle priority to all events
+  unless their priority is explicitly set.
+
+  Note that urgent-priority events can starve less-urgent events: after
+  running all urgent-priority callbacks, Libevent checks for more urgent
+  events again, before running less-urgent events.  Less-urgent events
+  will not have their callbacks run until there are no events more urgent
+  than them that want to be active.
+
+  @param eb the event_base structure returned by event_base_new()
   @param npriorities the maximum number of priorities
   @return 0 if successful, or -1 if an error occurred
-  @see event_priority_init(), event_priority_set()
+  @see event_priority_set()
  */
 int	event_base_priority_init(struct event_base *, int);
 
-
 /**
   Assign a priority to an event.
 
@@ -726,14 +1121,15 @@ int	event_base_priority_init(struct event_base *, int);
 int	event_priority_set(struct event *, int);
 
 /**
-   Prepare Libevent to use a large number of timeouts with the same duration.
+   Prepare an event_base to use a large number of timeouts with the same
+   duration.
 
    Libevent's default scheduling algorithm is optimized for having a large
-   number of timeouts with their durations more or less randomly distributed.
-   If you have a large number of timeouts that all have the same duration (for
-   example, if you have a large number of connections that all have a
-   10-second timeout), then you can improve Libevent's performance by telling
-   Libevent about it.
+   number of timeouts with their durations more or less randomly
+   distributed.  But if you have a large number of timeouts that all have
+   the same duration (for example, if you have a large number of
+   connections that all have a 10-second timeout), then you can improve
+   Libevent's performance by telling Libevent about it.
 
    To do this, call this function with the common duration.  It will return a
    pointer to a different, opaque timeout value.  (Don't depend on its actual
@@ -746,14 +1142,13 @@ int	event_priority_set(struct event *, int);
 const struct timeval *event_base_init_common_timeout(struct event_base *base,
     const struct timeval *duration);
 
-#ifndef _EVENT_DISABLE_MM_REPLACEMENT
+#if !defined(_EVENT_DISABLE_MM_REPLACEMENT) || defined(_EVENT_IN_DOXYGEN)
 /**
  Override the functions that Libevent uses for memory management.
 
  Usually, Libevent uses the standard libc functions malloc, realloc, and
  free to allocate memory.  Passing replacements for those functions to
- event_set_mem_functions() overrides this behavior.  To restore the default
- behavior, pass NULLs as the arguments to this function.
+ event_set_mem_functions() overrides this behavior.
 
  Note that all memory returned from Libevent will be allocated by the
  replacement functions rather than by malloc() and realloc().  Thus, if you
@@ -761,6 +1156,11 @@ const struct timeval *event_base_init_common_timeout(struct event_base *base,
  that you get from Libevent.  Instead, you must use the free_fn replacement
  that you provided.
 
+ Note also that if you are going to call this function, you should do so
+ before any call to any Libevent function that does allocation.
+ Otherwise, those funtions will allocate their memory using malloc(), but
+ then later free it using your provided free_fn.
+
  @param malloc_fn A replacement for malloc.
  @param realloc_fn A replacement for realloc
  @param free_fn A replacement for free.
@@ -769,6 +1169,8 @@ void event_set_mem_functions(
 	void *(*malloc_fn)(size_t sz),
 	void *(*realloc_fn)(void *ptr, size_t sz),
 	void (*free_fn)(void *ptr));
+/** This definition is present if Libevent was built with support for
+    event_set_mem_functions() */
 #define EVENT_SET_MEM_FUNCTIONS_IMPLEMENTED
 #endif
 
diff --git a/include/event2/event_compat.h b/include/event2/event_compat.h
index af2d0e0a..d501ef7d 100644
--- a/include/event2/event_compat.h
+++ b/include/event2/event_compat.h
@@ -27,11 +27,19 @@
 #ifndef _EVENT2_EVENT_COMPAT_H_
 #define _EVENT2_EVENT_COMPAT_H_
 
-/** @file event_compat.h
+/** @file event2/event_compat.h
 
   Potentially non-threadsafe versions of the functions in event.h: provided
   only for backwards compatibility.
 
+  In the oldest versions of Libevent, event_base was not a first-class
+  structure.  Instead, there was a single event base that every function
+  manipulated.  Later, when separate event bases were added, the old functions
+  that didn't take an event_base argument needed to work by manipulating the
+  "current" event base.  This could lead to thread-safety issues, and obscure,
+  hard-to-diagnose bugs.
+
+  @deprecated All functions in this file are by definition deprecated.
  */
 
 #ifdef __cplusplus
@@ -67,31 +75,26 @@ struct event_base *event_init(void);
 /**
   Loop to process events.
 
-  In order to process events, an application needs to call
-  event_dispatch().  This function only returns on error, and should
-  replace the event core of the application program.
+  Like event_base_dispatch(), but uses the "current" base.
 
   @deprecated This function is deprecated because it is easily confused by
     multiple calls to event_init(), and because it is not safe for
     multithreaded use.  The replacement is event_base_dispatch().
 
-  @see event_base_dispatch()
+  @see event_base_dispatch(), event_init()
  */
 int event_dispatch(void);
 
 /**
   Handle events.
 
-  This is a more flexible version of event_dispatch().
+  This function behaves like event_base_loop(), but uses the "current" base
 
   @deprecated This function is deprecated because it uses the event base from
     the last call to event_init, and is therefore not safe for multithreaded
     use.  The replacement is event_base_loop().
 
-  @param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK
-  @return 0 if successful, -1 if an error occurred, or 1 if no events were
-    registered.
-  @see event_base_loopexit(), event_base_loop()
+  @see event_base_loop(), event_init()
 */
 int event_loop(int);
 
@@ -99,19 +102,14 @@ int event_loop(int);
 /**
   Exit the event loop after the specified time.
 
-  The next event_loop() iteration after the given timer expires will
-  complete normally (handling all queued events) then exit without
-  blocking for events again.
-
-  Subsequent invocations of event_loop() will proceed normally.
+  This function behaves like event_base_loopexit(), except that it uses the
+  "current" base.
 
-  @deprecated This function is deprecated because it is easily confused by
-    multiple calls to event_init(), and because it is not safe for
-    multithreaded use.  The replacement is event_base_loopexit().
+  @deprecated This function is deprecated because it uses the event base from
+    the last call to event_init, and is therefore not safe for multithreaded
+    use.  The replacement is event_base_loopexit().
 
-  @param tv the amount of time after which the loop should terminate.
-  @return 0 if successful, or -1 if an error occurred
-  @see event_loop(), event_base_loop(), event_base_loopexit()
+  @see event_init, event_base_loopexit()
   */
 int event_loopexit(const struct timeval *);
 
@@ -119,42 +117,25 @@ int event_loopexit(const struct timeval *);
 /**
   Abort the active event_loop() immediately.
 
-  event_loop() will abort the loop after the next event is completed;
-  event_loopbreak() is typically invoked from this event's callback.
-  This behavior is analogous to the "break;" statement.
-
-  Subsequent invocations of event_loop() will proceed normally.
+  This function behaves like event_base_loopbreakt(), except that it uses the
+  "current" base.
 
-  @deprecated This function is deprecated because it is easily confused by
-    multiple calls to event_init(), and because it is not safe for
-    multithreaded use.  The replacement is event_base_loopbreak().
+  @deprecated This function is deprecated because it uses the event base from
+    the last call to event_init, and is therefore not safe for multithreaded
+    use.  The replacement is event_base_loopbreak().
 
-  @return 0 if successful, or -1 if an error occurred
-  @see event_base_loopbreak(), event_loopexit()
+  @see event_base_loopbreak(), event_init()
  */
 int event_loopbreak(void);
 
 /**
   Schedule a one-time event to occur.
 
-  The function event_once() is similar to event_set().  However, it schedules
-  a callback to be called exactly once and does not require the caller to
-  prepare an event structure.
-
-  @deprecated This function is deprecated because it is easily confused by
-    multiple calls to event_init(), and because it is not safe for
-    multithreaded use.  The replacement is event_base_once().
-
-  @param fd a file descriptor to monitor
-  @param events event(s) to monitor; can be any of EV_TIMEOUT | EV_READ |
-         EV_WRITE
-  @param callback callback function to be invoked when the event occurs
-  @param arg an argument to be passed to the callback function
-  @param timeout the maximum amount of time to wait for the event, or NULL
-         to wait forever
-  @return 0 if successful, or -1 if an error occurred
-  @see event_set()
+  @deprecated This function is obsolete, and has been replaced by
+    event_base_once(). Its use is deprecated because it relies on the
+    "current" base configured by event_init().
 
+  @see event_base_once()
  */
 int event_once(evutil_socket_t , short,
     void (*)(evutil_socket_t, short, void *), void *, const struct timeval *);
@@ -163,11 +144,11 @@ int event_once(evutil_socket_t , short,
 /**
   Get the kernel event notification mechanism used by Libevent.
 
-  @return a string identifying the kernel event mechanism (kqueue, epoll, etc.)
+  @deprecated This function is obsolete, and has been replaced by
+    event_base_get_method(). Its use is deprecated because it relies on the
+    "current" base configured by event_init().
 
-  @deprecated This function is deprecated because it is easily confused by
-    multiple calls to event_init(), and because it is not safe for
-    multithreaded use.  The replacement is event_base_get_method().
+  @see event_base_get_method()
  */
 const char *event_get_method(void);
 
@@ -175,61 +156,19 @@ const char *event_get_method(void);
 /**
   Set the number of different event priorities.
 
-  By default Libevent schedules all active events with the same priority.
-  However, some time it is desirable to process some events with a higher
-  priority than others.  For that reason, Libevent supports strict priority
-  queues.  Active events with a lower priority are always processed before
-  events with a higher priority.
-
-  The number of different priorities can be set initially with the
-  event_priority_init() function.  This function should be called before the
-  first call to event_dispatch().  The event_priority_set() function can be
-  used to assign a priority to an event.  By default, Libevent assigns the
-  middle priority to all events unless their priority is explicitly set.
-
   @deprecated This function is deprecated because it is easily confused by
     multiple calls to event_init(), and because it is not safe for
     multithreaded use.  The replacement is event_base_priority_init().
 
-  @param npriorities the maximum number of priorities
-  @return 0 if successful, or -1 if an error occurred
-  @see event_base_priority_init(), event_priority_set()
-
+  @see event_base_priority_init()
  */
 int	event_priority_init(int);
 
 /**
   Prepare an event structure to be added.
 
-  The function event_set() prepares the event structure ev to be used in
-  future calls to event_add() and event_del().  The event will be prepared to
-  call the function specified by the fn argument with an int argument
-  indicating the file descriptor, a short argument indicating the type of
-  event, and a void * argument given in the arg argument.  The fd indicates
-  the file descriptor that should be monitored for events.  The events can be
-  either EV_READ, EV_WRITE, or both.  Indicating that an application can read
-  or write from the file descriptor respectively without blocking.
-
-  The function fn will be called with the file descriptor that triggered the
-  event and the type of event which will be either EV_TIMEOUT, EV_SIGNAL,
-  EV_READ, or EV_WRITE.  The additional flag EV_PERSIST makes an event_add()
-  persistent until event_del() has been called.
-
-  For read and write events, edge-triggered behavior can be requested
-  with the EV_ET flag.  Not all backends support edge-triggered
-  behavior.  When an edge-triggered event is activated, the EV_ET flag
-  is added to its events argument.
-
-  @param ev an event struct to be modified
-  @param fd the file descriptor to be monitored
-  @param event desired events to monitor; can be EV_READ and/or EV_WRITE
-  @param fn callback function to be invoked when the event occurs
-  @param arg an argument to be passed to the callback function
-
-  @see event_add(), event_del(), event_once()
-
   @deprecated event_set() is not recommended for new code, because it requires
-     a subsequent call to event_base_set() to be safe under many circumstances.
+     a subsequent call to event_base_set() to be safe under most circumstances.
      Use event_assign() or event_new() instead.
  */
 void event_set(struct event *, evutil_socket_t, short, void (*)(evutil_socket_t, short, void *), void *);
@@ -240,76 +179,33 @@ void event_set(struct event *, evutil_socket_t, short, void (*)(evutil_socket_t,
 
 
 /**
- * Add a timeout event.
- *
- * @param ev the event struct to be disabled
- * @param tv the timeout value, in seconds
- *
- * @deprecated This macro is deprecated because its naming is inconsistent.
- *    The recommend macro is evtimer_add().
- */
-#define timeout_add(ev, tv)		event_add((ev), (tv))
-
+   @name timeout_* macros
 
-/**
- * Define a timeout event.
- *
- * @param ev the event struct to be defined
- * @param cb the callback to be invoked when the timeout expires
- * @param arg the argument to be passed to the callback
- *
- * @deprecated This macro is deprecated because its naming is inconsistent.
- *    The recommend macro is evtimer_set().
+   @deprecated These macros are deprecated because their naming is inconsisten
+     with the rest of Libevent.  Use the evtimer_* macros instead.
+   @{
  */
+#define timeout_add(ev, tv)		event_add((ev), (tv))
 #define timeout_set(ev, cb, arg)	event_set((ev), -1, 0, (cb), (arg))
-
-/**
- * Disable a timeout event.
- *
- * @param ev the timeout event to be disabled
- *
- * @deprecated This macro is deprecated because its naming is inconsistent.
- *    The recommend macro is evtimer_del().
- */
 #define timeout_del(ev)			event_del(ev)
-
-/**
-   @deprecated This macro is deprecated because its naming is inconsistent.
-   The recommend macro is evtimer_pending().
-*/
 #define timeout_pending(ev, tv)		event_pending((ev), EV_TIMEOUT, (tv))
-/**
-   @deprecated This macro is deprecated because its naming is inconsistent.
-   The recommend macro is evtimer_initialized().
-*/
 #define timeout_initialized(ev)		event_initialized(ev)
+/**@}*/
 
 /**
-   @deprecated This macro is deprecated because its naming is inconsistent.
-    The recommend macro is evsignal_add().
-*/
+   @name signal_* macros
+
+   @deprecated These macros are deprecated because their naming is inconsisten
+     with the rest of Libevent.  Use the evsignal_* macros instead.
+   @{
+ */
 #define signal_add(ev, tv)		event_add((ev), (tv))
-/**
-   @deprecated This macro is deprecated because its naming is inconsistent.
-    The recommend macro is evsignal_set().
-*/
 #define signal_set(ev, x, cb, arg)				\
 	event_set((ev), (x), EV_SIGNAL|EV_PERSIST, (cb), (arg))
-/**
-   @deprecated This macro is deprecated because its naming is inconsistent.
-    The recommend macro is evsignal_del().
-*/
 #define signal_del(ev)			event_del(ev)
-/**
-   @deprecated This macro is deprecated because its naming is inconsistent.
-    The recommend macro is evsignal_pending().
-*/
 #define signal_pending(ev, tv)		event_pending((ev), EV_SIGNAL, (tv))
-/**
-   @deprecated This macro is deprecated because its naming is inconsistent.
-    The recommend macro is evsignal_initialized().
-*/
 #define signal_initialized(ev)		event_initialized(ev)
+/**@}*/
 
 #ifndef EVENT_FD
 /* These macros are obsolete; use event_get_fd and event_get_signal instead. */
diff --git a/include/event2/event_struct.h b/include/event2/event_struct.h
index 4138ffd2..d3cfb0cc 100644
--- a/include/event2/event_struct.h
+++ b/include/event2/event_struct.h
@@ -27,11 +27,13 @@
 #ifndef _EVENT2_EVENT_STRUCT_H_
 #define _EVENT2_EVENT_STRUCT_H_
 
-/** @file event_struct.h
+/** @file event2/event_struct.h
 
-  Structures used by event.h.  Using these structures directly may harm
-  forward compatibility: be careful!
+  Structures used by event.h.  Using these structures directly WILL harm
+  forward compatibility: be careful.
 
+  No field declared in this file should be used directly in user code.  Except
+  for historical reasons, these fields would not be exposed at all.
  */
 
 #ifdef __cplusplus
diff --git a/include/event2/http.h b/include/event2/http.h
index 322240d9..760d7627 100644
--- a/include/event2/http.h
+++ b/include/event2/http.h
@@ -38,7 +38,7 @@ extern "C" {
 struct evbuffer;
 struct event_base;
 
-/** @file http.h
+/** @file event2/http.h
  *
  * Basic support for HTTP serving.
  *
diff --git a/include/event2/http_compat.h b/include/event2/http_compat.h
index b23dd9e0..02a080be 100644
--- a/include/event2/http_compat.h
+++ b/include/event2/http_compat.h
@@ -27,7 +27,7 @@
 #ifndef _EVENT2_HTTP_COMPAT_H_
 #define _EVENT2_HTTP_COMPAT_H_
 
-/** @file http_compat.h
+/** @file event2/http_compat.h
 
   Potentially non-threadsafe versions of the functions in http.h: provided
   only for backwards compatibility.
diff --git a/include/event2/http_struct.h b/include/event2/http_struct.h
index 7a68d4e5..3545fdf5 100644
--- a/include/event2/http_struct.h
+++ b/include/event2/http_struct.h
@@ -27,7 +27,7 @@
 #ifndef _EVENT2_HTTP_STRUCT_H_
 #define _EVENT2_HTTP_STRUCT_H_
 
-/** @file http_struct.h
+/** @file event2/http_struct.h
 
   Data structures for http.  Using these structures may hurt forward
   compatibility with later versions of Libevent: be careful!
diff --git a/include/event2/rpc_compat.h b/include/event2/rpc_compat.h
index af1ef99f..1f3b3a1f 100644
--- a/include/event2/rpc_compat.h
+++ b/include/event2/rpc_compat.h
@@ -27,7 +27,7 @@
 #ifndef _EVENT2_RPC_COMPAT_H_
 #define _EVENT2_RPC_COMPAT_H_
 
-/** @file rpc_compat.h
+/** @file event2/rpc_compat.h
 
   Deprecated versions of the functions in rpc.h: provided only for
   backwards compatibility.
diff --git a/include/event2/rpc_struct.h b/include/event2/rpc_struct.h
index c1efe1d8..1345fb74 100644
--- a/include/event2/rpc_struct.h
+++ b/include/event2/rpc_struct.h
@@ -31,7 +31,7 @@
 extern "C" {
 #endif
 
-/** @file rpc_struct.h
+/** @file event2/rpc_struct.h
 
   Structures used by rpc.h.  Using these structures directly may harm
   forward compatibility: be careful!
diff --git a/include/event2/tag.h b/include/event2/tag.h
index 7ab2346b..54ce8c65 100644
--- a/include/event2/tag.h
+++ b/include/event2/tag.h
@@ -27,7 +27,7 @@
 #ifndef _EVENT2_TAG_H_
 #define _EVENT2_TAG_H_
 
-/** @file tag.h
+/** @file event2/tag.h
 
   Helper functions for reading and writing tagged data onto buffers.
 
diff --git a/include/event2/tag_compat.h b/include/event2/tag_compat.h
index 41015740..8a47e8a3 100644
--- a/include/event2/tag_compat.h
+++ b/include/event2/tag_compat.h
@@ -27,13 +27,23 @@
 #ifndef _EVENT2_TAG_COMPAT_H_
 #define _EVENT2_TAG_COMPAT_H_
 
-/** @file tag_compat.h
+/** @file event2/tag_compat.h
 
     Obsolete/deprecated functions from tag.h; provided only for backwards
     compatibility.
  */
 
+/**
+   @name Misnamed functions
+
+   @deprecated These macros are deprecated because their names don't follow
+     Libevent's naming conventions.  Use evtag_encode_int and
+     evtag_encode_int64 instead.
+
+   @{
+*/
 #define encode_int(evbuf, number) evtag_encode_int((evbuf), (number))
 #define encode_int64(evbuf, number) evtag_encode_int64((evbuf), (number))
+/**@}*/
 
 #endif /* _EVENT2_TAG_H_ */
diff --git a/include/event2/thread.h b/include/event2/thread.h
index f51bf3ef..2cf11aa8 100644
--- a/include/event2/thread.h
+++ b/include/event2/thread.h
@@ -26,7 +26,7 @@
 #ifndef _EVENT2_THREAD_H_
 #define _EVENT2_THREAD_H_
 
-/** @file thread.h
+/** @file event2/thread.h
 
   Functions for multi-threaded applications using Libevent.
 
@@ -38,18 +38,11 @@
   _must_ be set up before an event_base is created if you want the base to
   use them.
 
-  A multi-threaded application must provide locking functions to
-  Libevent via evthread_set_locking_callback().  Libevent will invoke
-  this callback whenever a lock needs to be acquired or released.
-
-  The total number of locks employed by Libevent can be determined
-  via the evthread_num_locks() function.  An application must provision
-  that many locks.
-
-  If the owner of an event base is waiting for events to happen,
-  Libevent may signal the thread via a special file descriptor to wake
-  up.   To enable this feature, an application needs to provide a
-  thread identity function via evthread_set_id_callback().
+  Most programs will either be using Windows threads or Posix threads.  You
+  can configure Libevent to use one of these event_use_windows_threads() or
+  event_use_pthreads() respectively.  If you're using another threading
+  library, you'll need to configure threading functions manually using
+  evthread_set_lock_callbacks() and evthread_set_condition_callbacks().
 
  */
 
@@ -59,6 +52,11 @@ extern "C" {
 
 #include <event2/event-config.h>
 
+/**
+   @name Flags passed to lock functions
+
+   @{
+*/
 /** A flag passed to a locking callback when the lock was allocated as a
  * read-write lock, and we want to acquire or release the lock for writing. */
 #define EVTHREAD_WRITE	0x04
@@ -69,11 +67,16 @@ extern "C" {
  * for the lock; if we can't get the lock immediately, we will instead
  * return nonzero from the locking callback. */
 #define EVTHREAD_TRY    0x10
+/**@}*/
 
-#ifndef _EVENT_DISABLE_THREAD_SUPPORT
+#if !defined(_EVENT_DISABLE_THREAD_SUPPORT) || defined(_EVENT_IN_DOXYGEN)
 
 #define EVTHREAD_LOCK_API_VERSION 1
 
+/**
+   @name Types of locks
+
+   @{*/
 /** A recursive lock is one that can be acquired multiple times at once by the
  * same thread.  No other process can allocate the lock until the thread that
  * has been holding it has unlocked it as many times as it locked it. */
@@ -81,9 +84,10 @@ extern "C" {
 /* A read-write lock is one that allows multiple simultaneous readers, but
  * where any one writer excludes all other writers and readers. */
 #define EVTHREAD_LOCKTYPE_READWRITE 2
+/**@}*/
 
 /** This structure describes the interface a threading library uses for
- * locking.   It's used to tell evthread_set_lock_callbacks how to use
+ * locking.   It's used to tell evthread_set_lock_callbacks() how to use
  * locking on this platform.
  */
 struct evthread_lock_callbacks {
@@ -168,7 +172,7 @@ struct evthread_condition_callbacks {
  *
  * Note that if you're using Windows or the Pthreads threading library, you
  * probably shouldn't call this function; instead, use
- * evthread_use_windows_threads() or evthread_use_posix_threads() if you can.
+ * evthread_use_windows_threads() or evthread_use_pthreads() if you can.
  */
 int evthread_set_condition_callbacks(
 	const struct evthread_condition_callbacks *);
@@ -183,38 +187,45 @@ int evthread_set_condition_callbacks(
 void evthread_set_id_callback(
     unsigned long (*id_fn)(void));
 
-#if defined(WIN32) && !defined(_EVENT_DISABLE_THREAD_SUPPORT)
+#if (defined(WIN32) && !defined(_EVENT_DISABLE_THREAD_SUPPORT)) || defined(_EVENT_IN_DOXYGEN)
 /** Sets up Libevent for use with Windows builtin locking and thread ID
-	functions.  Unavailable if Libevent is not built for Windows.
+    functions.  Unavailable if Libevent is not built for Windows.
 
-	@return 0 on success, -1 on failure. */
+    @return 0 on success, -1 on failure. */
 int evthread_use_windows_threads(void);
+/**
+   Defined if Libevent was built with support for evthread_use_windows_threads()
+*/
 #define EVTHREAD_USE_WINDOWS_THREADS_IMPLEMENTED 1
 #endif
 
-#if defined(_EVENT_HAVE_PTHREADS)
+#if defined(_EVENT_HAVE_PTHREADS) || defined(_EVENT_IN_DOXYGEN)
 /** Sets up Libevent for use with Pthreads locking and thread ID functions.
-	Unavailable if Libevent is not build for use with pthreads.  Requires
-	libraries to link against Libevent_pthreads as well as Libevent.
+    Unavailable if Libevent is not build for use with pthreads.  Requires
+    libraries to link against Libevent_pthreads as well as Libevent.
 
-	@return 0 on success, -1 on failure. */
+    @return 0 on success, -1 on failure. */
 int evthread_use_pthreads(void);
+/** Defined if Libevent was built with support for evthread_use_pthreads() */
 #define EVTHREAD_USE_PTHREADS_IMPLEMENTED 1
 
 #endif
 
 /** Enable debugging wrappers around the current lock callbacks.  If Libevent
  * makes one of several common locking errors, exit with an assertion failure.
+ *
+ * If you're going to call this function, you must do so before any locks are
+ * allocated.
  **/
 void evthread_enable_lock_debuging(void);
 
 #endif /* _EVENT_DISABLE_THREAD_SUPPORT */
 
 struct event_base;
-/** Make sure it's safe to tell an event base to wake up from another thread.
+/** Make sure it's safe to tell an event base to wake up from another thread
     or a signal handler.
 
-	@return 0 on success, -1 on failure.
+    @return 0 on success, -1 on failure.
  */
 int evthread_make_base_notifiable(struct event_base *base);
 
diff --git a/include/event2/util.h b/include/event2/util.h
index cada314a..67fa809f 100644
--- a/include/event2/util.h
+++ b/include/event2/util.h
@@ -69,19 +69,39 @@ extern "C" {
 #include <sys/socket.h>
 #endif
 
-/* Integer type definitions for types that are supposed to be defined in the
+/* Some openbsd autoconf versions get the name of this macro wrong. */
+#if defined(_EVENT_SIZEOF_VOID__) && !defined(_EVENT_SIZEOF_VOID_P)
+#define _EVENT_SIZEOF_VOID_P _EVENT_SIZEOF_VOID__
+#endif
+
+/**
+ * @name Standard integer types.
+ *
+ * Integer type definitions for types that are supposed to be defined in the
  * C99-specified stdint.h.  Shamefully, some platforms do not include
  * stdint.h, so we need to replace it.  (If you are on a platform like this,
  * your C headers are now over 10 years out of date.  You should bug them to
  * do something about this.)
  *
  * We define:
- *    ev_uint64_t, ev_uint32_t, ev_uint16_t, ev_uint8_t -- unsigned integer
- *      types of exactly 64, 32, 16, and 8 bits respectively.
- *    ev_int64_t, ev_int32_t, ev_int16_t, ev_int8_t -- signed integer
- *      types of exactly 64, 32, 16, and 8 bits respectively.
- *    ev_uintptr_t, ev_intptr_t -- unsigned/signed integers large enough
- *      to hold a pointer without loss of bits.
+ *
+ * <dl>
+ *   <dt>ev_uint64_t, ev_uint32_t, ev_uint16_t, ev_uint8_t</dt>
+ *      <dd>unsigned integer types of exactly 64, 32, 16, and 8 bits
+ *          respectively.</dd>
+ *    <dt>ev_int64_t, ev_int32_t, ev_int16_t, ev_int8_t</dt>
+ *      <dd>signed integer types of exactly 64, 32, 16, and 8 bits
+ *          respectively.</dd>
+ *    <dt>ev_uintptr_t, ev_intptr_t</dt>
+ *      <dd>unsigned/signed integers large enough
+ *      to hold a pointer without loss of bits.</dd>
+ *    <dt>ev_ssize_t</dt>
+ *      <dd>A signed type of the same size as size_t</dd>
+ *    <dt>ev_off_t</dt>
+ *      <dd>A signed type typically used to represent offsets within a
+ *      (potentially large) file</dd>
+ *
+ * @{
  */
 #ifdef _EVENT_HAVE_UINT64_T
 #define ev_uint64_t uint64_t
@@ -95,6 +115,9 @@ extern "C" {
 #elif _EVENT_SIZEOF_LONG == 8
 #define ev_uint64_t unsigned long
 #define ev_int64_t long
+#elif defined(_EVENT_IN_DOXYGEN)
+#define ev_uint64_t ...
+#define ev_int64_t ...
 #else
 #error "No way to define ev_uint64_t"
 #endif
@@ -111,6 +134,9 @@ extern "C" {
 #elif _EVENT_SIZEOF_INT == 4
 #define ev_uint32_t unsigned int
 #define ev_int32_t signed int
+#elif defined(_EVENT_IN_DOXYGEN)
+#define ev_uint32_t ...
+#define ev_int32_t ...
 #else
 #error "No way to define ev_uint32_t"
 #endif
@@ -127,6 +153,9 @@ extern "C" {
 #elif _EVENT_SIZEOF_SHORT == 2
 #define ev_uint16_t unsigned short
 #define ev_int16_t  signed short
+#elif defined(_EVENT_IN_DOXYGEN)
+#define ev_uint16_t ...
+#define ev_int16_t ...
 #else
 #error "No way to define ev_uint16_t"
 #endif
@@ -134,16 +163,14 @@ extern "C" {
 #ifdef _EVENT_HAVE_UINT8_T
 #define ev_uint8_t uint8_t
 #define ev_int8_t int8_t
+#elif defined(_EVENT_IN_DOXYGEN)
+#define ev_uint8_t ...
+#define ev_int8_t ...
 #else
 #define ev_uint8_t unsigned char
 #define ev_int8_t signed char
 #endif
 
-/* Some openbsd autoconf versions get the name of this macro wrong. */
-#if defined(_EVENT_SIZEOF_VOID__) && !defined(_EVENT_SIZEOF_VOID_P)
-#define _EVENT_SIZEOF_VOID_P _EVENT_SIZEOF_VOID__
-#endif
-
 #ifdef _EVENT_HAVE_UINTPTR_T
 #define ev_uintptr_t uintptr_t
 #define ev_intptr_t intptr_t
@@ -153,6 +180,9 @@ extern "C" {
 #elif _EVENT_SIZEOF_VOID_P <= 8
 #define ev_uintptr_t ev_uint64_t
 #define ev_intptr_t ev_int64_t
+#elif defined(_EVENT_IN_DOXYGEN)
+#define ev_uintptr_t ...
+#define ev_intptr_t ...
 #else
 #error "No way to define ev_uintptr_t"
 #endif
@@ -168,6 +198,7 @@ extern "C" {
 #else
 #define ev_off_t off_t
 #endif
+/**@}*/
 
 /* Limits for integer types.
 
@@ -176,6 +207,14 @@ extern "C" {
      - The platform does signed arithmetic in two's complement.
 */
 
+/**
+   @name Limits for integer types
+
+   These macros hold the largest or smallest values possible for the
+   ev_[u]int*_t types.
+
+   @{
+*/
 #define EV_UINT64_MAX ((((ev_uint64_t)0xffffffffUL) << 32) | 0xffffffffUL)
 #define EV_INT64_MAX  ((((ev_int64_t) 0x7fffffffL) << 32) | 0xffffffffL)
 #define EV_INT64_MIN  ((-EV_INT64_MAX) - 1)
@@ -188,18 +227,28 @@ extern "C" {
 #define EV_UINT8_MAX  255
 #define EV_INT8_MAX   127
 #define EV_INT8_MIN   ((-EV_INT8_MAX) - 1)
+/** @} */
+
+/**
+   @name Limits for SIZE_T and SSIZE_T
 
+   @{
+*/
 #if _EVENT_SIZEOF_SIZE_T == 8
 #define EV_SIZE_MAX EV_UINT64_MAX
 #define EV_SSIZE_MAX EV_INT64_MAX
 #elif _EVENT_SIZEOF_SIZE_T == 4
 #define EV_SIZE_MAX EV_UINT32_MAX
 #define EV_SSIZE_MAX EV_INT32_MAX
+#elif defined(_EVENT_IN_DOXYGEN)
+#define EV_SIZE_MAX ...
+#define EV_SSIZE_MAX ...
 #else
 #error "No way to define SIZE_MAX"
 #endif
 
 #define EV_SSIZE_MIN ((-EV_SSIZE_MAX) - 1)
+/**@}*/
 
 #ifdef WIN32
 #define ev_socklen_t int
@@ -216,17 +265,20 @@ extern "C" {
 #endif
 #endif
 
-#ifdef WIN32
-/** A type wide enough to hold the output of "socket()" or "accept()".  On
+/**
+ * A type wide enough to hold the output of "socket()" or "accept()".  On
  * Windows, this is an intptr_t; elsewhere, it is an int. */
+#ifdef WIN32
 #define evutil_socket_t intptr_t
 #else
 #define evutil_socket_t int
 #endif
 
-/** Create two new sockets that are connected to each other.  On Unix, this
-    simply calls socketpair().  On Windows, it uses the loopback network
-    interface on 127.0.0.1, and only AF_INET,SOCK_STREAM are supported.
+/** Create two new sockets that are connected to each other.
+
+    On Unix, this simply calls socketpair().  On Windows, it uses the
+    loopback network interface on 127.0.0.1, and only
+    AF_INET,SOCK_STREAM are supported.
 
     (This may fail on some Windows hosts where firewall software has cleverly
     decided to keep 127.0.0.1 from talking to itself.)
@@ -241,9 +293,13 @@ int evutil_socketpair(int d, int type, int protocol, evutil_socket_t sv[2]);
  */
 int evutil_make_socket_nonblocking(evutil_socket_t sock);
 
-/** Do platform-specific operations on a listener socket to make sure that
-    another program will be able to bind this address right after we've
-    closed the listener
+/** Do platform-specific operations to make a listener socket reusable.
+
+    Specifically, we want to make sure that another program will be able
+    to bind this address right after we've closed the listener.
+
+    This differs from Windows's interpretation of "reusable", which
+    allows multiple listeners to bind the same address at the same time.
 
     @param sock The socket to make reusable
     @return 0 on success, -1 on failure
@@ -267,11 +323,6 @@ int evutil_make_socket_closeonexec(evutil_socket_t sock);
 int evutil_closesocket(evutil_socket_t sock);
 #define EVUTIL_CLOSESOCKET(s) evutil_closesocket(s)
 
-/* Winsock handles socket errors differently from the rest of the world.
- * Elsewhere, a socket error is like any other error and is stored in errno.
- * But winsock functions require you to retrieve the error with a special
- * function, and don't let you use strerror for the error codes.  And handling
- * EWOULDBLOCK is ... different. */
 
 #ifdef WIN32
 /** Return the most recent socket error.  Not idempotent on all platforms. */
@@ -283,6 +334,30 @@ int evutil_closesocket(evutil_socket_t sock);
 int evutil_socket_geterror(evutil_socket_t sock);
 /** Convert a socket error to a string. */
 const char *evutil_socket_error_to_string(int errcode);
+#elif defined(_EVENT_IN_DOXYGEN)
+/**
+   @name Socket error functions
+
+   These functions are needed for making programs compatible between
+   Windows and Unix-like platforms.
+
+   You see, Winsock handles socket errors differently from the rest of
+   the world.  Elsewhere, a socket error is like any other error and is
+   stored in errno.  But winsock functions require you to retrieve the
+   error with a special function, and don't let you use strerror for
+   the error codes.  And handling EWOULDBLOCK is ... different.
+
+   @{
+*/
+/** Return the most recent socket error.  Not idempotent on all platforms. */
+#define EVUTIL_SOCKET_ERROR() ...
+/** Replace the most recent socket error with errcode */
+#define EVUTIL_SET_SOCKET_ERROR(errcode) ...
+/** Return the most recent socket error to occur on sock. */
+#define evutil_socket_geterror(sock) ...
+/** Convert a socket error to a string. */
+#define evutil_socket_error_to_string(errcode) ...
+/**@}*/
 #else
 #define EVUTIL_SOCKET_ERROR() (errno)
 #define EVUTIL_SET_SOCKET_ERROR(errcode)		\
@@ -291,9 +366,14 @@ const char *evutil_socket_error_to_string(int errcode);
 #define evutil_socket_error_to_string(errcode) (strerror(errcode))
 #endif
 
-/*
- * Manipulation macros for struct timeval.  We define replacements
+
+/**
+ * @name Manipulation macros for struct timeval.
+ *
+ * We define replacements
  * for timeradd, timersub, timerclear, timercmp, and timerisset.
+ *
+ * @{
  */
 #ifdef _EVENT_HAVE_TIMERADD
 #define evutil_timeradd(tvp, uvp, vvp) timeradd((tvp), (uvp), (vvp))
@@ -324,6 +404,7 @@ const char *evutil_socket_error_to_string(int errcode);
 #else
 #define	evutil_timerclear(tvp)	(tvp)->tv_sec = (tvp)->tv_usec = 0
 #endif
+/**@}*/
 
 /** Return true iff the tvp is related to uvp according to the relational
  * operator cmp.  Recognized values for cmp are ==, <=, <, >=, and >. */
@@ -338,7 +419,7 @@ const char *evutil_socket_error_to_string(int errcode);
 #define	evutil_timerisset(tvp)	((tvp)->tv_sec || (tvp)->tv_usec)
 #endif
 
-/* Replacement for offsetof on platforms that don't define it. */
+/** Replacement for offsetof on platforms that don't define it. */
 #ifdef offsetof
 #define evutil_offsetof(type, field) offsetof(type, field)
 #else
@@ -349,7 +430,7 @@ const char *evutil_socket_error_to_string(int errcode);
 /** Parse a 64-bit value from a string.  Arguments are as for strtol. */
 ev_int64_t evutil_strtoll(const char *s, char **endptr, int base);
 
-/* Replacement for gettimeofday on platforms that lack it. */
+/** Replacement for gettimeofday on platforms that lack it. */
 #ifdef _EVENT_HAVE_GETTIMEOFDAY
 #define evutil_gettimeofday(tv, tz) gettimeofday((tv), (tz))
 #else
@@ -365,6 +446,9 @@ int evutil_snprintf(char *buf, size_t buflen, const char *format, ...)
 	__attribute__((format(printf, 3, 4)))
 #endif
 ;
+/** Replacement for vsnprintf to get consistent behavior on platforms for
+    which the return value of snprintf does not conform to C99.
+ */
 int evutil_vsnprintf(char *buf, size_t buflen, const char *format, va_list ap);
 
 /** Replacement for inet_ntop for platforms which lack it. */
@@ -412,11 +496,16 @@ int evutil_ascii_strcasecmp(const char *str1, const char *str2);
  */
 int evutil_ascii_strncasecmp(const char *str1, const char *str2, size_t n);
 
-/* Here we define evutil_addrinfo to the native addrinfo type, or redefinte it
+/* Here we define evutil_addrinfo to the native addrinfo type, or redefine it
  * if this system has no getaddrinfo(). */
 #ifdef _EVENT_HAVE_STRUCT_ADDRINFO
 #define evutil_addrinfo addrinfo
 #else
+/** A definition of struct addrinfo for systems that lack it.
+
+    (This is just an alias for struct addrinfo if the system defines
+    struct addrinfo.)
+*/
 struct evutil_addrinfo {
 	int     ai_flags;     /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
 	int     ai_family;    /* PF_xxx */
@@ -428,6 +517,13 @@ struct evutil_addrinfo {
 	struct evutil_addrinfo  *ai_next; /* next structure in linked list */
 };
 #endif
+/** @name evutil_getaddrinfo() error codes
+
+    These values are possible error codes for evutil_getaddrinfo() and
+    related functions.
+
+    @{
+*/
 #ifdef EAI_ADDRFAMILY
 #define EVUTIL_EAI_ADDRFAMILY EAI_ADDRFAMILY
 #else
@@ -524,9 +620,11 @@ struct evutil_addrinfo {
 #else
 #define EVUTIL_AI_ADDRCONFIG 0x40000
 #endif
+/**@}*/
 
 struct evutil_addrinfo;
-/* This function clones getaddrinfo for systems that don't have it.  For full
+/**
+ * This function clones getaddrinfo for systems that don't have it.  For full
  * details, see RFC 3493, section 6.1.
  *
  * Limitations:
@@ -539,12 +637,12 @@ struct evutil_addrinfo;
 int evutil_getaddrinfo(const char *nodename, const char *servname,
     const struct evutil_addrinfo *hints_in, struct evutil_addrinfo **res);
 
-/* Release storage allocated by evutil_getaddrinfo or evdns_getaddrinfo. */
+/** Release storage allocated by evutil_getaddrinfo or evdns_getaddrinfo. */
 void evutil_freeaddrinfo(struct evutil_addrinfo *ai);
 
 const char *evutil_gai_strerror(int err);
 
-/* Generate n bytes of secure pseudorandom data, and store them in buf.
+/** Generate n bytes of secure pseudorandom data, and store them in buf.
  *
  * By default, Libevent uses an ARC4-based random number generator, seeded
  * using the platform's entropy source (/dev/urandom on Unix-like systems;