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

Submitted by Srivardhan Hebbar on Oct. 15, 2014, 9:21 a.m.

Details

Message ID 1413364887-19198-1-git-send-email-sri.hebbar@samsung.com
State Accepted
Headers show

Not browsing as part of any series.

Commit Message

Srivardhan Hebbar Oct. 15, 2014, 9:21 a.m.
Signed-off-by: Srivardhan Hebbar <sri.hebbar@samsung.com>
---
 src/wayland-server.c | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

Patch hide | download patch | download mbox

diff --git a/src/wayland-server.c b/src/wayland-server.c
index 674aeca..0fc2088 100644
--- a/src/wayland-server.c
+++ b/src/wayland-server.c
@@ -862,6 +862,18 @@  wl_socket_alloc(void)
 	return s;
 }
 
+/** Destroy Wayland display object.
+ *
+ * \param display The Wayland display object which should be destroyed.
+ * \return None.
+ *
+ * This function sends a destroy signal to all registered clients, releases
+ * all the sockets added to this display, free's all the globals associated
+ * with this display, free's memory of additional shared memory formats and
+ * destroy the display object.
+ *
+ * \memberof wl_display
+ */
 WL_EXPORT void
 wl_display_destroy(struct wl_display *display)
 {
@@ -1181,6 +1193,27 @@  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.
+ * If NULL is passed as name, then it would look for WAYLAND_DISPLAY env
+ * variable for the socket name. If WAYLAND_DISPLAY is not set, then default
+ * wayland-0 is used.
+ * The Unix socket would be created in the path which is set in env
+ * variable XDG_RUNTIME_DIR. If XDG_RUNTIME_DIR is not set, then this function
+ * fails and returns -1.
+ * The length of socket path, i.e., the path set in XDG_RUNTIME_DIR and the
+ * socket name should not exceed 108 characters. Else this would fail.
+ * The function also fails if the user do not have write permission in the
+ * XDG_RUNTIME_DIR path or if the socket name is already in use.
+ *
+ * \memberof wl_display
+ */
 WL_EXPORT int
 wl_display_add_socket(struct wl_display *display, const char *name)
 {

Comments

On Wed, 15 Oct 2014 14:51:27 +0530
Srivardhan Hebbar <sri.hebbar@samsung.com> wrote:

> Signed-off-by: Srivardhan Hebbar <sri.hebbar@samsung.com>
> ---
>  src/wayland-server.c | 33 +++++++++++++++++++++++++++++++++
>  1 file changed, 33 insertions(+)
> 
> diff --git a/src/wayland-server.c b/src/wayland-server.c
> index 674aeca..0fc2088 100644
> --- a/src/wayland-server.c
> +++ b/src/wayland-server.c
> @@ -862,6 +862,18 @@ wl_socket_alloc(void)
>  	return s;
>  }
>  
> +/** Destroy Wayland display object.
> + *
> + * \param display The Wayland display object which should be destroyed.
> + * \return None.
> + *
> + * This function sends a destroy signal to all registered clients, releases

Sorry, what exactly are the registered clients? If this is referring to

	wl_signal_emit(&display->destroy_signal, display);

it would be better to say "emits the wl_display destroy signal", since
I'm not sure what the "registered clients" are. This would refer to
wl_display_add_destroy_listener() which we could mention as see-also
here.

> + * all the sockets added to this display, free's all the globals associated
> + * with this display, free's memory of additional shared memory formats and
> + * destroy the display object.
> + *
> + * \memberof wl_display
> + */
>  WL_EXPORT void
>  wl_display_destroy(struct wl_display *display)
>  {
> @@ -1181,6 +1193,27 @@ 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.
> + * If NULL is passed as name, then it would look for WAYLAND_DISPLAY env
> + * variable for the socket name. If WAYLAND_DISPLAY is not set, then default
> + * wayland-0 is used.
> + * The Unix socket would be created in the path which is set in env
> + * variable XDG_RUNTIME_DIR. If XDG_RUNTIME_DIR is not set, then this function
> + * fails and returns -1.
> + * The length of socket path, i.e., the path set in XDG_RUNTIME_DIR and the
> + * socket name should not exceed 108 characters. Else this would fail.
> + * The function also fails if the user do not have write permission in the
> + * XDG_RUNTIME_DIR path or if the socket name is already in use.
> + *
> + * \memberof wl_display
> + */
>  WL_EXPORT int
>  wl_display_add_socket(struct wl_display *display, const char *name)
>  {

Actually, I fixed the above comment myself, and reworded a little more.
With the changes, pushed.

Bryce, thanks for the reviews.


Thanks,
pq