diff --git a/doc/src/api/init/chapter.xml b/doc/src/api/init/chapter.xml
index 69f64571..90495f44 100644
--- a/doc/src/api/init/chapter.xml
+++ b/doc/src/api/init/chapter.xml
@@ -10,8 +10,7 @@
 <!ENTITY scdetectcardpresence SYSTEM "sc_detect_card_presence.xml">
 <!ENTITY sccardvalid SYSTEM "sc_card_valid.xml">
 <!ENTITY scsetcarddriver SYSTEM "sc_set_card_driver.xml">
-
-<!ENTITY includes "#include &lt;opensc.h&gt;">
+<!ENTITY scwaitforevent SYSTEM "sc_wait_for_event.xml">
 ]>
 
 <chapter>
diff --git a/doc/src/api/init/sc_wait_for_event.xml b/doc/src/api/init/sc_wait_for_event.xml
index 6b867d14..618fe12e 100644
--- a/doc/src/api/init/sc_wait_for_event.xml
+++ b/doc/src/api/init/sc_wait_for_event.xml
@@ -1,4 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
 <refentry id="scwaitforevent">
+	<refentryinfo><title>OpenSC API Reference</title></refentryinfo>
 	<refmeta>
 		<refentrytitle>sc_wait_for_event</refentrytitle>
 		<manvolnum>3</manvolnum>
@@ -14,9 +16,9 @@
 		<title>Synopsis</title>
 		<para>
 		<programlisting>
-&includes;
+#include &lt;opensc.h&gt;
 
-int sc_wait_for_event(sc_reader_t *readers[], int slot_id[], size_t nslots,
+int sc_wait_for_event(sc_reader_t *readers[], int slots[], size_t numslots,
                       unsigned int event_mask,
                       int *reader, unsigned int *event, int timeout);
 		</programlisting>
@@ -26,10 +28,43 @@ int sc_wait_for_event(sc_reader_t *readers[], int slot_id[], size_t nslots,
 	<refsect1>
 		<title>Description</title>
 		<para>
-			This function blocks until an event occurs on the reader spec
+			This function blocks until an event occurs on any of the
+			readers/slots specified. The <emphasis>readers</emphasis> and
+			<emphasis>slots</emphasis> fields list the readers and the
+			respective slots to be watched. <emphasis>num_slots</emphasis>
+			holds the total number of slots passed. The <emphasis>event_mask</emphasis>
+			parameter specifies the types of events to wait for. This may a
+			combination of the following flags:
+			<variablelist>
+				<varlistentry>
+					<term><symbol>SC_EVENT_CARD_REMOVED</symbol></term>
+					<listitem><para>A card was removed from the reader/slot.</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><symbol>SC_EVENT_CARD_INSERTED</symbol></term>
+					<listitem><para>A card was insert into the reader/slot.</para></listitem>
+				</varlistentry>
+			</variablelist>
 		</para>
 
 		<para>
+			On returning, the <emphasis>reader</emphasis> parameter holds the
+			reader which generated an event, and <emphasis>event</emphasis> holds
+			the event flag, as in <emphasis>event_mask</emphasis>.
+		</para>
+
+		<para>
+			The timeout parameter may be used to specify the maximum amount of
+			time to wait for an event, in milliseconds. This may be set to -1
+			to wait forever.
+		</para>
+	</refsect1>
+
+	<refsect1>
+		<title>Return value</title>
+		<para>
+			Returns 0 if successful, 1 if a timeout occurred, or a negative
+			value in case of error.
 		</para>
 	</refsect1>