From: Michael Poole <mdpoole@troilus.org>
Date: Tue, 5 Oct 2004 01:26:58 +0000 (+0000)
Subject: Doxyfy engine_*.c.
X-Git-Url: http://git.pk910.de/?a=commitdiff_plain;h=e5fa429e2429bff9c1344a810ed97a8c47362b04;p=ircu2.10.12-pk.git

Doxyfy engine_*.c.


git-svn-id: file:///home/klmitch/undernet-ircu/undernet-ircu-svn/ircu2/trunk@1218 c9e4aea6-c8fd-4c43-8297-357d70d61c8c
---

diff --git a/ircd/engine_devpoll.c b/ircd/engine_devpoll.c
index 5cf7eff..9c4d49c 100644
--- a/ircd/engine_devpoll.c
+++ b/ircd/engine_devpoll.c
@@ -15,8 +15,10 @@
  * You should have received a copy of the GNU General Public License
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- * $Id$
+ */
+/** @file
+ * @brief Solaris /dev/poll event engine.
+ * @version $Id$
  */
 #include "config.h"
 
@@ -38,8 +40,8 @@
 #include <sys/types.h>
 #include <unistd.h>
 
-#define DEVPOLL_ERROR_THRESHOLD	20	/* after 20 devpoll errors, restart */
-#define ERROR_EXPIRE_TIME	3600	/* expire errors after an hour */
+#define DEVPOLL_ERROR_THRESHOLD	20	/**< after 20 devpoll errors, restart */
+#define ERROR_EXPIRE_TIME	3600	/**< expire errors after an hour */
 
 /* Figure out what bits to set for read */
 #if defined(POLLMSG) && defined(POLLIN) && defined(POLLRDNORM)
@@ -61,14 +63,21 @@
 #  define POLLWRITEFLAGS POLLWRNORM
 #endif
 
+/** Array of active Socket structures, indexed by file descriptor. */
 static struct Socket** sockList;
+/** Maximum file descriptor supported, plus one. */
 static int devpoll_max;
+/** File descriptor for /dev/poll device. */
 static int devpoll_fd;
 
+/** Number of recent errors from /dev/poll. */
 static int errors = 0;
+/** Periodic timer to forget errors. */
 static struct Timer clear_error;
 
-/* decrements the error count once per hour */
+/** Decrement the error count (once per hour).
+ * @param[in] ev Expired timer event (ignored).
+ */
 static void
 error_clear(struct Event* ev)
 {
@@ -76,7 +85,10 @@ error_clear(struct Event* ev)
     timer_del(ev_timer(ev));
 }
 
-/* initialize the devpoll engine */
+/** Initialize the /dev/poll engine.
+ * @param[in] max_sockets Maximum number of file descriptors to support.
+ * @return Non-zero on success, or zero on failure.
+ */
 static int
 engine_init(int max_sockets)
 {
@@ -100,7 +112,11 @@ engine_init(int max_sockets)
   return 1;
 }
 
-/* Figure out what events go with a given state */
+/** Figure out what events go with a given state.
+ * @param[in] state %Socket state to consider.
+ * @param[in] events User-specified preferred event set.
+ * @return Actual set of preferred events.
+ */
 static unsigned int
 state_to_events(enum SocketState state, unsigned int events)
 {
@@ -123,7 +139,10 @@ state_to_events(enum SocketState state, unsigned int events)
   return 0;
 }
 
-/* Reset the desired events */
+/** Set the desired events for a socket.
+ * @param[in,out] sock Socket to operate on.
+ * @param[in] events User-specified preferred event set.
+ */
 static void
 set_events(struct Socket* sock, unsigned int events)
 {
@@ -166,7 +185,10 @@ set_events(struct Socket* sock, unsigned int events)
   s_ed_int(sock) = 1; /* mark that we've added a pollfd */
 }
 
-/* add a socket to be listened on */
+/** Add a socket to the event engine.
+ * @param[in] sock Socket to add to engine.
+ * @return Non-zero on success, or zero on error.
+ */
 static int
 engine_add(struct Socket* sock)
 {
@@ -192,7 +214,10 @@ engine_add(struct Socket* sock)
   return 1; /* success */
 }
 
-/* socket switching to new state */
+/** Handle state transition for a socket.
+ * @param[in] sock Socket changing state.
+ * @param[in] new_state New state for socket.
+ */
 static void
 engine_state(struct Socket* sock, enum SocketState new_state)
 {
@@ -206,7 +231,10 @@ engine_state(struct Socket* sock, enum SocketState new_state)
   set_events(sock, state_to_events(new_state, s_events(sock)));
 }
 
-/* socket events changing */
+/** Handle change to preferred socket events.
+ * @param[in] sock Socket getting new interest list.
+ * @param[in] new_events New set of interesting events for socket.
+ */
 static void
 engine_events(struct Socket* sock, unsigned int new_events)
 {
@@ -220,7 +248,9 @@ engine_events(struct Socket* sock, unsigned int new_events)
   set_events(sock, state_to_events(s_state(sock), new_events));
 }
 
-/* socket going away */
+/** Remove a socket from the event engine.
+ * @param[in] sock Socket being destroyed.
+ */
 static void
 engine_delete(struct Socket* sock)
 {
@@ -235,7 +265,9 @@ engine_delete(struct Socket* sock)
   sockList[s_fd(sock)] = 0; /* zero the socket list entry */
 }
 
-/* engine event loop */
+/** Run engine event loop.
+ * @param[in] gen Lists of generators of various types.
+ */
 static void
 engine_loop(struct Generators* gen)
 {
@@ -407,6 +439,7 @@ engine_loop(struct Generators* gen)
   }
 }
 
+/** Descriptor for /dev/poll event engine. */
 struct Engine engine_devpoll = {
   "/dev/poll",		/* Engine name */
   engine_init,		/* Engine initialization function */
diff --git a/ircd/engine_epoll.c b/ircd/engine_epoll.c
index 6680dac..1016e55 100644
--- a/ircd/engine_epoll.c
+++ b/ircd/engine_epoll.c
@@ -15,8 +15,10 @@
  * You should have received a copy of the GNU General Public License
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- * $Id$
+ */
+/** @file
+ * @brief Linux epoll_*() event engine.
+ * @version $Id$
  */
 #include "config.h"
 
@@ -69,14 +71,19 @@ _syscall4(int, epoll_wait, int, epfd, struct epoll_event *, pevents, int, maxeve
 
 #endif /* epoll_create defined as stub */
 
-#define EPOLL_ERROR_THRESHOLD 20   /* after 20 epoll errors, restart */
-#define ERROR_EXPIRE_TIME     3600 /* expire errors after an hour */
+#define EPOLL_ERROR_THRESHOLD 20   /**< after 20 epoll errors, restart */
+#define ERROR_EXPIRE_TIME     3600 /**< expire errors after an hour */
 
+/** File descriptor for epoll pseudo-file. */
 static int epoll_fd;
+/** Number of recent epoll errors. */
 static int errors;
+/** Periodic timer to forget errors. */
 static struct Timer clear_error;
 
-/* decrements the error count once per hour */
+/** Decrement the error count (once per hour).
+ * @param[in] ev Expired timer event (ignored).
+ */
 static void
 error_clear(struct Event *ev)
 {
@@ -84,7 +91,10 @@ error_clear(struct Event *ev)
     timer_del(ev_timer(ev));
 }
 
-/* initialize the epoll engine */
+/** Initialize the epoll engine.
+ * @param[in] max_sockets Maximum number of file descriptors to support.
+ * @return Non-zero on success, or zero on failure.
+ */
 static int
 engine_init(int max_sockets)
 {
@@ -96,6 +106,12 @@ engine_init(int max_sockets)
   return 1;
 }
 
+/** Set events for a particular socket.
+ * @param[in] sock Socket to calculate events for.
+ * @param[in] state Current socket state.
+ * @param[in] events User-specified event interest list.
+ * @param[out] evt epoll event structure for socket.
+ */
 static void
 set_events(struct Socket *sock, enum SocketState state, unsigned int events, struct epoll_event *evt)
 {
@@ -136,6 +152,10 @@ set_events(struct Socket *sock, enum SocketState state, unsigned int events, str
   }
 }
 
+/** Add a socket to the event engine.
+ * @param[in] sock Socket to add to engine.
+ * @return Non-zero on success, or zero on error.
+ */
 static int
 engine_add(struct Socket *sock)
 {
@@ -152,6 +172,10 @@ engine_add(struct Socket *sock)
   return 1;
 }
 
+/** Handle state transition for a socket.
+ * @param[in] sock Socket changing state.
+ * @param[in] new_state New state for socket.
+ */
 static void
 engine_set_state(struct Socket *sock, enum SocketState new_state)
 {
@@ -165,6 +189,10 @@ engine_set_state(struct Socket *sock, enum SocketState new_state)
     event_generate(ET_ERROR, sock, errno);
 }
 
+/** Handle change to preferred socket events.
+ * @param[in] sock Socket getting new interest list.
+ * @param[in] new_events New set of interesting events for socket.
+ */
 static void
 engine_set_events(struct Socket *sock, unsigned new_events)
 {
@@ -178,6 +206,9 @@ engine_set_events(struct Socket *sock, unsigned new_events)
     event_generate(ET_ERROR, sock, errno);
 }
 
+/** Remove a socket from the event engine.
+ * @param[in] sock Socket being destroyed.
+ */
 static void
 engine_delete(struct Socket *sock)
 {
@@ -192,6 +223,9 @@ engine_delete(struct Socket *sock)
               "Unable to delete epoll item for socket %d", s_fd(sock));
 }
 
+/** Run engine event loop.
+ * @param[in] gen Lists of generators of various types.
+ */
 static void
 engine_loop(struct Generators *gen)
 {
@@ -282,6 +316,7 @@ engine_loop(struct Generators *gen)
   }
 }
 
+/** Descriptor for dpoll event engine. */
 struct Engine engine_epoll = {
   "epoll()",
   engine_init,
diff --git a/ircd/engine_kqueue.c b/ircd/engine_kqueue.c
index 892c595..914a09c 100644
--- a/ircd/engine_kqueue.c
+++ b/ircd/engine_kqueue.c
@@ -15,8 +15,10 @@
  * You should have received a copy of the GNU General Public License
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- * $Id$
+ */
+/** @file
+ * @brief FreeBSD kqueue()/kevent() event engine.
+ * @version $Id$
  */
 #include "config.h"
 
@@ -38,17 +40,24 @@
 #include <time.h>
 #include <unistd.h>
 
-#define KQUEUE_ERROR_THRESHOLD	20	/* after 20 kqueue errors, restart */
-#define ERROR_EXPIRE_TIME	3600	/* expire errors after an hour */
+#define KQUEUE_ERROR_THRESHOLD	20	/**< after 20 kqueue errors, restart */
+#define ERROR_EXPIRE_TIME	3600	/**< expire errors after an hour */
 
+/** Array of active Socket structures, indexed by file descriptor. */
 static struct Socket** sockList;
+/** Maximum file descriptor supported, plus one. */
 static int kqueue_max;
+/** File descriptor for kqueue pseudo-file. */
 static int kqueue_id;
 
+/** Number of recent errors from kqueue. */
 static int errors = 0;
+/** Periodic timer to forget errors. */
 static struct Timer clear_error;
 
-/* decrements the error count once per hour */
+/** Decrement the error count (once per hour).
+ * @param[in] ev Expired timer event (ignored).
+ */
 static void
 error_clear(struct Event* ev)
 {
@@ -56,7 +65,10 @@ error_clear(struct Event* ev)
     timer_del(ev_timer(ev));
 }
 
-/* initialize the kqueue engine */
+/** Initialize the kqueue engine.
+ * @param[in] max_sockets Maximum number of file descriptors to support.
+ * @return Non-zero on success, or zero on failure.
+ */
 static int
 engine_init(int max_sockets)
 {
@@ -80,7 +92,9 @@ engine_init(int max_sockets)
   return 1; /* success! */
 }
 
-/* add a signel to be watched for */
+/** Add a signal to the event engine.
+ * @param[in] sig Signal to add to engine.
+ */
 static void
 engine_signal(struct Signal* sig)
 {
@@ -111,7 +125,11 @@ engine_signal(struct Signal* sig)
   sigaction(sig_signal(sig), &act, 0);
 }
 
-/* Figure out what events go with a given state */
+/** Figure out what events go with a given state.
+ * @param[in] state %Socket state to consider.
+ * @param[in] events User-specified preferred event set.
+ * @return Actual set of preferred events.
+ */
 static unsigned int
 state_to_events(enum SocketState state, unsigned int events)
 {
@@ -134,7 +152,11 @@ state_to_events(enum SocketState state, unsigned int events)
   return 0;
 }
 
-/* Activate kqueue filters as appropriate */
+/** Activate kqueue filters as appropriate.
+ * @param[in] sock Socket structure to operate on.
+ * @param[in] clear Set of interest events to clear from socket.
+ * @param[in] set Set of interest events to set on socket.
+ */
 static void
 set_or_clear(struct Socket* sock, unsigned int clear, unsigned int set)
 {
@@ -180,7 +202,10 @@ set_or_clear(struct Socket* sock, unsigned int clear, unsigned int set)
     event_generate(ET_ERROR, sock, errno); /* report error */
 }
 
-/* add a socket to be listened on */
+/** Add a socket to the event engine.
+ * @param[in] sock Socket to add to engine.
+ * @return Non-zero on success, or zero on error.
+ */
 static int
 engine_add(struct Socket* sock)
 {
@@ -206,7 +231,10 @@ engine_add(struct Socket* sock)
   return 1; /* success */
 }
 
-/* socket switching to new state */
+/** Handle state transition for a socket.
+ * @param[in] sock Socket changing state.
+ * @param[in] new_state New state for socket.
+ */
 static void
 engine_state(struct Socket* sock, enum SocketState new_state)
 {
@@ -223,7 +251,10 @@ engine_state(struct Socket* sock, enum SocketState new_state)
 
 }
 
-/* socket events changing */
+/** Handle change to preferred socket events.
+ * @param[in] sock Socket getting new interest list.
+ * @param[in] new_events New set of interesting events for socket.
+ */
 static void
 engine_events(struct Socket* sock, unsigned int new_events)
 {
@@ -239,7 +270,9 @@ engine_events(struct Socket* sock, unsigned int new_events)
 	       state_to_events(s_state(sock), new_events)); /* new events */
 }
 
-/* socket going away */
+/** Remove a socket from the event engine.
+ * @param[in] sock Socket being destroyed.
+ */
 static void
 engine_delete(struct Socket* sock)
 {
@@ -273,7 +306,9 @@ engine_delete(struct Socket* sock)
   sockList[s_fd(sock)] = 0;
 }
 
-/* engine event loop */
+/** Run engine event loop.
+ * @param[in] gen Lists of generators of various types.
+ */
 static void
 engine_loop(struct Generators* gen)
 {
@@ -411,6 +446,7 @@ engine_loop(struct Generators* gen)
   }
 }
 
+/** Descriptor for kqueue() event engine. */
 struct Engine engine_kqueue = {
   "kqueue()",		/* Engine name */
   engine_init,		/* Engine initialization function */
diff --git a/ircd/engine_poll.c b/ircd/engine_poll.c
index fe52249..58b3f9e 100644
--- a/ircd/engine_poll.c
+++ b/ircd/engine_poll.c
@@ -15,8 +15,10 @@
  * You should have received a copy of the GNU General Public License
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- * $Id$
+ */
+/** @file
+ * @brief POSIX poll() event engine.
+ * @version $Id$
  */
 #include "config.h"
 
@@ -35,8 +37,8 @@
 #include <time.h>
 #include <unistd.h>
 
-#define POLL_ERROR_THRESHOLD	20	/* after 20 poll errors, restart */
-#define ERROR_EXPIRE_TIME	3600	/* expire errors after an hour */
+#define POLL_ERROR_THRESHOLD	20	/**< after 20 poll errors, restart */
+#define ERROR_EXPIRE_TIME	3600	/**< expire errors after an hour */
 
 /* Figure out what bits to set for read */
 #if defined(POLLMSG) && defined(POLLIN) && defined(POLLRDNORM)
@@ -58,15 +60,23 @@
 #  define POLLWRITEFLAGS POLLWRNORM
 #endif
 
+/** Array of active Socket structures, indexed by file descriptor. */
 static struct Socket** sockList;
+/** Array of poll() active elements. */
 static struct pollfd* pollfdList;
+/** Number of pollfd elements currently used. */
 static unsigned int poll_count;
+/** Maximum file descriptor supported, plus one. */
 static unsigned int poll_max;
 
+/** Number of recent errors from poll(). */
 static int errors = 0;
+/** Periodic timer to forget errors. */
 static struct Timer clear_error;
 
-/* decrements the error count once per hour */
+/** Decrement the error count (once per hour).
+ * @param[in] ev Expired timer event (ignored).
+ */
 static void
 error_clear(struct Event* ev)
 {
@@ -74,7 +84,10 @@ error_clear(struct Event* ev)
     timer_del(ev_timer(ev));
 }
 
-/* initialize the poll engine */
+/** Initialize the poll() engine.
+ * @param[in] max_sockets Maximum number of file descriptors to support.
+ * @return Non-zero on success, or zero on failure.
+ */
 static int
 engine_init(int max_sockets)
 {
@@ -98,7 +111,11 @@ engine_init(int max_sockets)
   return 1;
 }
 
-/* Figure out what events go with a given state */
+/** Figure out what events go with a given state.
+ * @param[in] state %Socket state to consider.
+ * @param[in] events User-specified preferred event set.
+ * @return Actual set of preferred events.
+ */
 static unsigned int
 state_to_events(enum SocketState state, unsigned int events)
 {
@@ -121,7 +138,11 @@ state_to_events(enum SocketState state, unsigned int events)
   return 0;
 }
 
-/* Toggle bits in the pollfd structs correctly */
+/** Set interest events in a pollfd as appropriate.
+ * @param[in] idx Index of pollfd to operate on.
+ * @param[in] clear Set of interest events to clear from socket.
+ * @param[in] set Set of interest events to set on socket.
+ */
 static void
 set_or_clear(int idx, unsigned int clear, unsigned int set)
 {
@@ -140,7 +161,10 @@ set_or_clear(int idx, unsigned int clear, unsigned int set)
   }
 }
 
-/* add a socket to be listened on */
+/** Add a socket to the event engine.
+ * @param[in] sock Socket to add to engine.
+ * @return Non-zero on success, or zero on error.
+ */
 static int
 engine_add(struct Socket* sock)
 {
@@ -179,7 +203,10 @@ engine_add(struct Socket* sock)
   return 1; /* success */
 }
 
-/* socket switching to new state */
+/** Handle state transition for a socket.
+ * @param[in] sock Socket changing state.
+ * @param[in] new_state New state for socket.
+ */
 static void
 engine_state(struct Socket* sock, enum SocketState new_state)
 {
@@ -196,7 +223,10 @@ engine_state(struct Socket* sock, enum SocketState new_state)
 	       state_to_events(new_state, s_events(sock))); /* new state */
 }
 
-/* socket events changing */
+/** Handle change to preferred socket events.
+ * @param[in] sock Socket getting new interest list.
+ * @param[in] new_events New set of interesting events for socket.
+ */
 static void
 engine_events(struct Socket* sock, unsigned int new_events)
 {
@@ -213,7 +243,9 @@ engine_events(struct Socket* sock, unsigned int new_events)
 	       state_to_events(s_state(sock), new_events)); /* new events */
 }
 
-/* socket going away */
+/** Remove a socket from the event engine.
+ * @param[in] sock Socket being destroyed.
+ */
 static void
 engine_delete(struct Socket* sock)
 {
@@ -236,7 +268,9 @@ engine_delete(struct Socket* sock)
     poll_count--;
 }
 
-/* socket event loop */
+/** Run engine event loop.
+ * @param[in] gen Lists of generators of various types.
+ */
 static void
 engine_loop(struct Generators* gen)
 {
@@ -392,6 +426,7 @@ engine_loop(struct Generators* gen)
   }
 }
 
+/** Descriptor for poll() event engine. */
 struct Engine engine_poll = {
   "poll()",		/* Engine name */
   engine_init,		/* Engine initialization function */
diff --git a/ircd/engine_select.c b/ircd/engine_select.c
index eed3856..e759967 100644
--- a/ircd/engine_select.c
+++ b/ircd/engine_select.c
@@ -15,8 +15,10 @@
  * You should have received a copy of the GNU General Public License
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- * $Id$
+ */
+/** @file
+ * @brief BSD sockets select() event engine.
+ * @version $Id$
  */
 #include "config.h"
 
@@ -42,18 +44,26 @@
 #include <time.h>
 #include <unistd.h>
 
-#define SELECT_ERROR_THRESHOLD	20	/* after 20 select errors, restart */
-#define ERROR_EXPIRE_TIME	3600	/* expire errors after an hour */
+#define SELECT_ERROR_THRESHOLD	20	/**< after 20 select errors, restart */
+#define ERROR_EXPIRE_TIME	3600	/**< expire errors after an hour */
 
+/** Array of active Socket structures, indexed by file descriptor. */
 static struct Socket* sockList[FD_SETSIZE];
+/** Maximum file descriptor currently used. */
 static int highest_fd;
+/** Global read event interest bitmap. */
 static fd_set global_read_set;
+/** Global write event interest bitmap. */
 static fd_set global_write_set;
 
+/** Number of recent errors from select(). */
 static int errors = 0;
+/** Periodic timer to forget errors. */
 static struct Timer clear_error;
 
-/* decrements the error count once per hour */
+/** Decrement the error count (once per hour).
+ * @param[in] ev Expired timer event (ignored).
+ */
 static void
 error_clear(struct Event* ev)
 {
@@ -61,7 +71,10 @@ error_clear(struct Event* ev)
     timer_del(ev_timer(ev));
 }
 
-/* initialize the select engine */
+/** Initialize the select() engine.
+ * @param[in] max_sockets Maximum number of file descriptors to support.
+ * @return Non-zero on success, or zero on failure.
+ */
 static int
 engine_init(int max_sockets)
 {
@@ -85,7 +98,11 @@ engine_init(int max_sockets)
   return 1; /* initialization successful */
 }
 
-/* Figure out what events go with a given state */
+/** Figure out what events go with a given state.
+ * @param[in] state %Socket state to consider.
+ * @param[in] events User-specified preferred event set.
+ * @return Actual set of preferred events.
+ */
 static unsigned int
 state_to_events(enum SocketState state, unsigned int events)
 {
@@ -108,7 +125,11 @@ state_to_events(enum SocketState state, unsigned int events)
   return 0;
 }
 
-/* Toggle bits in the global fd sets appropriately */
+/** Set interest events in #global_read_set and #global_write_set as appropriate.
+ * @param[in] fd File descriptor to operate on.
+ * @param[in] clear Set of interest events to clear from socket.
+ * @param[in] set Set of interest events to set on socket.
+ */
 static void
 set_or_clear(int fd, unsigned int clear, unsigned int set)
 {
@@ -127,7 +148,10 @@ set_or_clear(int fd, unsigned int clear, unsigned int set)
   }
 }
 
-/* add a socket to be listened on */
+/** Add a socket to the event engine.
+ * @param[in] sock Socket to add to engine.
+ * @return Non-zero on success, or zero on error.
+ */
 static int
 engine_add(struct Socket* sock)
 {
@@ -156,7 +180,10 @@ engine_add(struct Socket* sock)
   return 1; /* success */
 }
 
-/* socket switching to new state */
+/** Handle state transition for a socket.
+ * @param[in] sock Socket changing state.
+ * @param[in] new_state New state for socket.
+ */
 static void
 engine_state(struct Socket* sock, enum SocketState new_state)
 {
@@ -172,7 +199,10 @@ engine_state(struct Socket* sock, enum SocketState new_state)
 	       state_to_events(new_state, s_events(sock))); /* new state */
 }
 
-/* socket events changing */
+/** Handle change to preferred socket events.
+ * @param[in] sock Socket getting new interest list.
+ * @param[in] new_events New set of interesting events for socket.
+ */
 static void
 engine_events(struct Socket* sock, unsigned int new_events)
 {
@@ -188,7 +218,9 @@ engine_events(struct Socket* sock, unsigned int new_events)
 	       state_to_events(s_state(sock), new_events)); /* new events */
 }
 
-/* socket going away */
+/** Remove a socket from the event engine.
+ * @param[in] sock Socket being destroyed.
+ */
 static void
 engine_delete(struct Socket* sock)
 {
@@ -207,7 +239,9 @@ engine_delete(struct Socket* sock)
     highest_fd--;
 }
 
-/* engine event loop */
+/** Run engine event loop.
+ * @param[in] gen Lists of generators of various types.
+ */
 static void
 engine_loop(struct Generators* gen)
 {
@@ -364,6 +398,7 @@ engine_loop(struct Generators* gen)
   }
 }
 
+/** Descriptor for select() event engine. */
 struct Engine engine_select = {
   "select()",		/* Engine name */
   engine_init,		/* Engine initialization function */