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

[Uli Schlachter]

On 11.06.2014 08:40, Alan Coopersmith wrote:
> 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>

Reviewed-by: Uli Schlachter <psychon at znc.in>

(Although the bike shedding me feels like suggesting "never returns NULL"
instead of "Always returns a structure" and making it clearer if/that(?)
xcb_disconnect() must always be called, even on error connections. However, your
wording is good enough for the not-bike-shedding me)

> ---
>  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);
>  
> 


-- 
<alanc> I think someone had a Xprint version of glxgears at one point,
    but benchmarking how many GL pages you can print per second
    was deemed too silly to merge