[Xcb] [PATCH:libxcb] Document failure modes of xcb_connect*() functions

[Alan Coopersmith]

Documentation was previously unclear that these always return a non-NULL
pointer, and that callers need to check it for error values, instead of
checking for a NULL return value.

Triggered by having to dig through code to answer a user's question on
the #xcb irc channel, since neither of us found it covered in the docs.

Signed-off-by: Alan Coopersmith <alan.coopersmith at oracle.com>
---
 src/xcb.h |   15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/src/xcb.h b/src/xcb.h
index c17a2ef..9ef135e 100644
--- a/src/xcb.h
+++ b/src/xcb.h
@@ -475,6 +475,11 @@ int xcb_connection_has_error(xcb_connection_t *c);
  * bidirectionally connected to an X server. If the connection
  * should be unauthenticated, @p auth_info must be @c
  * NULL.
+ *
+ * Always returns a xcb_connection_t structure, even on failure.
+ * Callers need to use xcb_connection_has_error() to check for failure.
+ * When finished, use xcb_disconnect() to close the connection and free
+ * the structure.
  */
 xcb_connection_t *xcb_connect_to_fd(int fd, xcb_auth_info_t *auth_info);
 
@@ -520,6 +525,11 @@ int xcb_parse_display(const char *name, char **host, int *display, int *screen);
  * variable. If a particular screen on that server is preferred, the
  * int pointed to by @p screenp (if not @c NULL) will be set to that
  * screen; otherwise the screen will be set to 0.
+ *
+ * Always returns a xcb_connection_t structure, even on failure.
+ * Callers need to use xcb_connection_has_error() to check for failure.
+ * When finished, use xcb_disconnect() to close the connection and free
+ * the structure.
  */
 xcb_connection_t *xcb_connect(const char *displayname, int *screenp);
 
@@ -534,6 +544,11 @@ xcb_connection_t *xcb_connect(const char *displayname, int *screenp);
  * authorization @p auth. If a particular screen on that server is
  * preferred, the int pointed to by @p screenp (if not @c NULL) will
  * be set to that screen; otherwise @p screenp will be set to 0.
+ *
+ * Always returns a xcb_connection_t structure, even on failure.
+ * Callers need to use xcb_connection_has_error() to check for failure.
+ * When finished, use xcb_disconnect() to close the connection and free
+ * the structure.
  */
 xcb_connection_t *xcb_connect_to_display_with_auth_info(const char *display, xcb_auth_info_t *auth, int *screen);
 
-- 
1.7.9.2