[PATCH] doc: Added API documentation for wl_display_destroy and wl_display_add_socket functions.

[Bryce Harrington]

On Mon, Oct 13, 2014 at 05:24:15PM +0530, Srivardhan Hebbar wrote:
> Signed-off-by: Srivardhan Hebbar <sri.hebbar at samsung.com>
> ---
>  src/wayland-server.c | 20 ++++++++++++++++++++
>  1 file changed, 20 insertions(+)
> 
> diff --git a/src/wayland-server.c b/src/wayland-server.c
> index 674aeca..0f61e6e 100644
> --- a/src/wayland-server.c
> +++ b/src/wayland-server.c
> @@ -862,6 +862,15 @@ wl_socket_alloc(void)
>  	return s;
>  }
>  
> +/** Destroy Wayland display object.
> + *
> + * \param display The Wayland display object which should be destroyed.
> + * \return None.
> + *
> + * This destroys the wl_display object which has been passed.

I think the reader could guess this from the function name.  ;-)

Might be more informative to mention that it frees the object itself,
along with freeing all contained sockets and globals, and releases any
additional shm formats.

> + * \memberof wl_display
> + */
>  WL_EXPORT void
>  wl_display_destroy(struct wl_display *display)
>  {
> @@ -1181,6 +1190,17 @@ wl_display_add_socket_auto(struct wl_display *display)
>  	return NULL;
>  }
>  
> +/** Add a socket to Wayland display for the clients to connect.
> + *
> + * \param display Wayland display to which the socket should be added.
> + * \param name Name of the Unix socket.
> + * \return 0 if success. -1 if failed.
> + *
> + * This adds a Unix socket to Wayland display which can be used by clients to
> + * connect to Wayland display.

Again, we should try to avoid adding documentation which merely restates
the function name, and try to say something meaningful.

There are three different ways the routine can fail, all of which return
-1; these three situations would be worth mentioning.

The routine attempts to use the WAYLAND_DISPLAY environment variable,
and if that's not set it assumes "wayland-0".  This behavior would also
be worth mentioning in the documentation.

Thanks for giving attention to the code documentation; this can be
invaluable to future end users.

Bryce