diff --git a/KNOWN_ISSUES b/KNOWN_ISSUES
index 4049a90..3d24752 100644
--- a/KNOWN_ISSUES
+++ b/KNOWN_ISSUES
@@ -1,4 +1,3 @@
-- API docs with examples on how to use this
 - Does the name still seem correct? Figuring out event names turned out to be
   more complicated than errors. Oh and we also handle requests...
 - Should releases come with pre-generated source?
diff --git a/src/xcb_errors.h b/src/xcb_errors.h
index 1a982ce..baa0ec6 100644
--- a/src/xcb_errors.h
+++ b/src/xcb_errors.h
@@ -55,14 +55,15 @@ typedef struct xcb_errors_context_t xcb_errors_context_t;
 int xcb_errors_context_new(xcb_connection_t *conn, xcb_errors_context_t **ctx);
 
 /**
- * Freed the @ref xcb_cursor_context_t.
+ * Free the @ref xcb_cursor_context_t.
  *
  * @param ctx The context to free.
  */
 void xcb_errors_context_free(xcb_errors_context_t *ctx);
 
 /**
- * Get the name corresponding to some major code.
+ * Get the name corresponding to some major code. This is either the name of
+ * some core request or the name of the extension that owns this major code.
  *
  * @param ctx An errors context, created with @ref xcb_errors_context_new ()
  * @param major_code The major code
@@ -74,7 +75,9 @@ const char *xcb_errors_get_name_for_major_code(xcb_errors_context_t *ctx,
 		uint8_t major_code);
 
 /**
- * Get the name corresponding to some minor code or NULL.
+ * Get the name corresponding to some minor code. When the major_code does not
+ * belong to any extension or the minor_code is not assigned inside this
+ * extension, NULL is returned.
  *
  * @param ctx An errors context, created with @ref xcb_errors_context_new ()
  * @param major_code The major code under which to look up the minor code
@@ -87,7 +90,8 @@ const char *xcb_errors_get_name_for_minor_code(xcb_errors_context_t *ctx,
 		uint16_t minor_code);
 
 /**
- * Get the name corresponding to some core event code.
+ * Get the name corresponding to some core event code. If possible, you should
+ * use @ref xcb_errors_get_name_for_xcb_event instead.
  *
  * @param ctx An errors context, created with @ref xcb_errors_context_new ()
  * @param event_code The response_type of an event.
@@ -106,6 +110,8 @@ const char *xcb_errors_get_name_for_core_event(xcb_errors_context_t *ctx,
  * use the X generic event extension, but implements its own event multiplexing.
  * This function also handles XKB's xkbType events as a event_type.
  *
+ * If possible, you should use @ref xcb_errors_get_name_for_xcb_event instead.
+ *
  * @param ctx An errors context, created with @ref xcb_errors_context_new ()
  * @param major_code The extension's major code
  * @param event_type The type of the event in that extension.