[Spice-devel] udscs: Improve the udscs API documentation

[Francois Gouget]

Document what happens whenever passing a NULL server or connection
pointer is allowed.
Make it clear that only pathname Unix domain sockets are supported.
Also document when no_types and the type_to_string array are used
and what for.

Signed-off-by: Francois Gouget <fgouget at codeweavers.com>
---
 src/udscs.h | 58 +++++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 47 insertions(+), 11 deletions(-)

diff --git a/src/udscs.h b/src/udscs.h
index 6e960f8..ed0e061 100644
--- a/src/udscs.h
+++ b/src/udscs.h
@@ -57,21 +57,38 @@ typedef void (*udscs_read_callback)(struct udscs_connection **connp,
  */
 typedef void (*udscs_disconnect_callback)(struct udscs_connection *conn);
 
-/* Connect to a unix domain socket named name. */
+/* Connect to the pathname unix domain socket specified by socketname.
+ *
+ * If debug is true then the events on this connection will be traced.
+ * This includes the incoming and outgoing message names. So when debug is true
+ * no_types must be set to the value of the highest valid message id + 1,
+ * and type_to_string must point to a string array of size no_types for
+ * converting the message ids to their names.
+ */
 struct udscs_connection *udscs_connect(const char *socketname,
     udscs_read_callback read_callback,
     udscs_disconnect_callback disconnect_callback,
     const char * const type_to_string[], int no_types, int debug);
 
-/* The contents of connp will be made NULL. */
+/* Closes the connection, releases the corresponding resources and
+ * sets *connp to NULL.
+ *
+ * Does nothing if *connp is NULL.
+ */
 void udscs_destroy_connection(struct udscs_connection **connp);
 
+/* Given a udscs client fill the fd_sets pointed to by readfds and
+ * writefds for select() usage.
+ * Return value: value of the highest fd + 1 or -1 if conn is NULL
+ */
 int udscs_client_fill_fds(struct udscs_connection *conn, fd_set *readfds,
     fd_set *writefds);
 
-/* Note the connection may be destroyed (when disconnected) by this call
- * in this case the disconnect calllback will get called before the
- * destruction and the contents of connp will be made NULL.
+/* Handle any events flagged by select for the given udscs client.
+ * Note that upon disconnection this will call the disconnect callback
+ * and then destroy the connection which will set *connp to NULL.
+ *
+ * Does nothing if *connp is NULL.
  */
 void udscs_client_handle_fds(struct udscs_connection **connp, fd_set *readfds,
     fd_set *writefds);
@@ -82,8 +99,12 @@ void udscs_client_handle_fds(struct udscs_connection **connp, fd_set *readfds,
 int udscs_write(struct udscs_connection *conn, uint32_t type, uint32_t arg1,
         uint32_t arg2, const uint8_t *data, uint32_t size);
 
-/* To associate per connection data with a connection. */
+/* Associates the specified user data with the connection. */
 void udscs_set_user_data(struct udscs_connection *conn, void *data);
+
+/* Returns the connection's associated user data.
+ * Returns NULL if conn is NULL.
+ */
 void *udscs_get_user_data(struct udscs_connection *conn);
 
 
@@ -98,13 +119,26 @@ struct udscs_server;
  */
 typedef void (*udscs_connect_callback)(struct udscs_connection *conn);
 
-/* Create a unix domain socket named name and start listening on it. */
+/* Create the pathname unix domain socket specified by socketname and
+ * start listening on it.
+ *
+ * If debug is true then the events on this socket and related individual
+ * connections will be traced.
+ * This includes the incoming and outgoing message names. So when debug is true
+ * no_types must be set to the value of the highest valid message id + 1,
+ * and type_to_string must point to a string array of size no_types for
+ * converting the message ids to their names.
+ */
 struct udscs_server *udscs_create_server(const char *socketname,
     udscs_connect_callback connect_callback,
     udscs_read_callback read_callback,
     udscs_disconnect_callback disconnect_callback,
     const char * const type_to_string[], int no_types, int debug);
 
+/* Closes all the server's connections and releases the corresponding
+ * resources.
+ * Does nothing if server is NULL.
+ */
 void udscs_destroy_server(struct udscs_server *server);
 
 /* Like udscs_write, but then send the message to all clients connected to
@@ -122,19 +156,21 @@ typedef int (*udscs_for_all_clients_callback)(struct udscs_connection **connp,
 
 /* Call func for all clients connected to the server, passing through
  * priv to all func calls. Returns the total of the return values from all
- * calls to func.
+ * calls to func or 0 if server is NULL.
  */
 int udscs_server_for_all_clients(struct udscs_server *server,
     udscs_for_all_clients_callback func, void *priv);
 
-/* Given an udscs server or client fill the fd_sets pointed to by readfds and
+/* Given a udscs server fill the fd_sets pointed to by readfds and
  * writefds for select() usage.
- * Return value: value of the highest fd + 1
+ * Return value: value of the highest fd + 1 or -1 if server is NULL
  */
 int udscs_server_fill_fds(struct udscs_server *server, fd_set *readfds,
     fd_set *writefds);
 
-/* Handle any events flagged by select for the given udscs server or client. */
+/* Handle any events flagged by select for the given udscs server.
+ * Does nothing if server is NULL.
+ */
 void udscs_server_handle_fds(struct udscs_server *server, fd_set *readfds,
     fd_set *writefds);
 
-- 
2.10.2