[PATCH wayland v2 2/5] wayland-server: Add code docs for new display socket API's

[Bryce Harrington]

Signed-off-by: Bryce Harrington <bryce at osg.samsung.com>
---
 src/wayland-server.c | 67 +++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 53 insertions(+), 14 deletions(-)

diff --git a/src/wayland-server.c b/src/wayland-server.c
index bac98bf..e84858d 100644
--- a/src/wayland-server.c
+++ b/src/wayland-server.c
@@ -1164,6 +1164,17 @@ _wl_display_add_socket(struct wl_display *display, struct wl_socket *s)
 	return 0;
 }
 
+/** Create a socket for clients with a specified file descriptor
+ * \param display Wayland display
+ * \param sock_fd The socket's file descriptor
+ * \return The socket name or NULL if failed.
+ *
+ * Adds a new socket with a specified file descriptor but an
+ * automatically determined socket name, in the form "wayland-N"
+ * where N is a display number.
+ *
+ * \memberof wl_display
+ */
 WL_EXPORT const char *
 wl_display_add_socket_fd_auto(struct wl_display *display, int sock_fd)
 {
@@ -1205,12 +1216,50 @@ wl_display_add_socket_fd_auto(struct wl_display *display, int sock_fd)
 	return NULL;
 }
 
+/** Create a socket for clients using default settings
+ * \param display The Wayland display to which the socket should be added
+ * \return The name of the created socket, or NULL if failed.
+ *
+ * This helper routine establishes a socket connection for Wayland clients
+ * using an automatically socket address and file descriptor.
+ *
+ * See wl_display_add_socket_fd_auto.
+ *
+ * \memberof wl_display
+ */
 WL_EXPORT const char *
 wl_display_add_socket_auto(struct wl_display *display)
 {
 	return wl_display_add_socket_fd_auto(display, -1);
 }
 
+/** Add a socket with a defined file descriptor to the Wayland display for clients to connect.
+ * \param display Wayland display to which the socket should be added.
+ * \param name Name of the Unix socket.
+ * \param sock_fd File descriptor 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.
+ *
+ * If -1 is passed for sock_id, a new local socket will be created.  A link to
+ * this socket will be made available in display->socket_list.
+ *
+ * This Unix socket will be created in the directory pointed to by environment
+ * 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, must not exceed the maxium length of a Unix socket path.
+ * 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_fd(struct wl_display *display, const char *name, int sock_fd)
 {
@@ -1251,21 +1300,11 @@ wl_display_add_socket_fd(struct wl_display *display, const char *name, int sock_
  * \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.
+ * This adds a Unix socket to Wayland display with an automatically
+ * created file descriptor, which can be used by clients to connect to
+ * the Wayland display.
  *
- * The Unix socket will be created in the directory pointed to by environment
- * 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, must not exceed the maxium length of a Unix socket path.
- * 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.
+ * See wl_display_add_socket_fd for more details.
  *
  * \memberof wl_display
  */
-- 
1.9.1