include/sock.h: add comments for public APIs

Change-Id: I791b942f5d8cd0f0780583f2dded5d5416ebe285
Signed-off-by: Yanbo Zhou <yanbo.zhou@intel.com>
Reviewed-on: https://review.gerrithub.io/411216
Tested-by: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: Ben Walker <benjamin.walker@intel.com>
Reviewed-by: Daniel Verkamp <daniel.verkamp@intel.com>

include/spdk/sock.h

@@ -47,29 +47,195 @@ extern "C" {
 struct spdk_sock;
 struct spdk_sock_group;
 
+/**
+ * Get client and server addresses of the given socket.
+ *
+ * \param sock Socket to get address.
+ * \param saddr A pointer to the buffer to hold the address of server.
+ * \param slen Length of the buffer 'saddr'.
+ * \param caddr A pointer to the buffer to hold the address of client.
+ * \param slen Length of the buffer 'caddr'.
+ *
+ * \return 0 on success, -1 on failure.
+ */
 int spdk_sock_getaddr(struct spdk_sock *sock, char *saddr, int slen, char *caddr, int clen);
+
+/**
+ * Create a socket, connect the socket to the specified address and port (of the
+ * server), and then return the socket. This function is used by client.
+ *
+ * \param ip IP address of the server.
+ * \param port Port number of the server.
+ *
+ * \return a pointer to the connected socket on success, or NULL on failure.
+ */
 struct spdk_sock *spdk_sock_connect(const char *ip, int port);
+
+/**
+ * Create a socket, bind the socket to the specified address and port and listen
+ * on the socket, and then return the socket. This function is used by server.
+ *
+ * \param ip IP address to listen on.
+ * \param port Port number.
+ *
+ * \return a pointer to the listened socket on success, or NULL on failure.
+ */
 struct spdk_sock *spdk_sock_listen(const char *ip, int port);
+
+/**
+ * Accept a new connection from a client on the specified socket and return a
+ * socket structure which holds the connection.
+ *
+ * \param sock Listening socket.
+ *
+ * \return a pointer to the accepted socket on success, or NULL on failure.
+ */
 struct spdk_sock *spdk_sock_accept(struct spdk_sock *sock);
+
+/**
+ * Close a socket.
+ *
+ * \param sock Socket to close.
+ *
+ * \return 0 on success, -1 on failure.
+ */
 int spdk_sock_close(struct spdk_sock **sock);
+
+/**
+ * Receive a message from the given socket.
+ *
+ * \param sock Socket to receive message.
+ * \param buf Pointer to a buffer to hold the data.
+ * \param len Length of the buffer.
+ *
+ * \return the length of the received message on success, -1 on failure.
+ */
 ssize_t spdk_sock_recv(struct spdk_sock *sock, void *buf, size_t len);
+
+/**
+ * Write message to the given socket from the I/O vector array.
+ *
+ * \param sock Socket to write to.
+ * \param iov I/O vector.
+ * \param iovcnt Number of I/O vectors in the array.
+ *
+ * \return the length of written message on success, -1 on failure.
+ */
 ssize_t spdk_sock_writev(struct spdk_sock *sock, struct iovec *iov, int iovcnt);
 
+/**
+ * Set the value used to specify the low water mark (in bytes) for this socket.
+ *
+ * \param sock Socket to set for.
+ * \param nbytes Value for recvlowat.
+ *
+ * \return 0 on success, -1 on failure.
+ */
 int spdk_sock_set_recvlowat(struct spdk_sock *sock, int nbytes);
+
+/**
+ * Set receive buffer size for the given socket.
+ *
+ * \param sock Socket to set buffer size for.
+ * \param sz Buffer size in bytes.
+ *
+ * \return 0 on success, -1 on failure.
+ */
 int spdk_sock_set_recvbuf(struct spdk_sock *sock, int sz);
+
+/**
+ * Set send buffer size for the given socket.
+ *
+ * \param sock Socket to set buffer size for.
+ * \param sz Buffer size in bytes.
+ *
+ * \return 0 on success, -1 on failure.
+ */
 int spdk_sock_set_sendbuf(struct spdk_sock *sock, int sz);
 
+/**
+ * Check whether the address of socket is ipv6.
+ *
+ * \param sock Socket to check.
+ *
+ * \return true if the address of socket is ipv6, or false otherwise.
+ */
 bool spdk_sock_is_ipv6(struct spdk_sock *sock);
+
+/**
+ * Check whether the address of socket is ipv4.
+ *
+ * \param sock Socket to check.
+ *
+ * \return true if the address of socket is ipv4, or false otherwise.
+ */
 bool spdk_sock_is_ipv4(struct spdk_sock *sock);
 
+/**
+ * Callback function for spdk_sock_group_add_sock().
+ *
+ * \param arg Argument for the callback function.
+ * \param group Socket group.
+ * \param sock Socket.
+ */
 typedef void (*spdk_sock_cb)(void *arg, struct spdk_sock_group *group, struct spdk_sock *sock);
 
+/**
+ * Create a new socket group.
+ *
+ * \return a pointer to the created group on success, or NULL on failure.
+ */
 struct spdk_sock_group *spdk_sock_group_create(void);
+
+/**
+ * Add a socket to the group.
+ *
+ * \param group Socket group.
+ * \param sock Socket to add.
+ * \param cb_fn Called when the operation completes.
+ * \param cb_arg Argument passed to the callback function.
+ *
+ * \return 0 on success, -1 on failure.
+ */
 int spdk_sock_group_add_sock(struct spdk_sock_group *group, struct spdk_sock *sock,
 			     spdk_sock_cb cb_fn, void *cb_arg);
+
+/**
+ * Remove a socket from the group.
+ *
+ * \param group Socket group.
+ * \param sock Socket to remove.
+ *
+ * \return 0 on success, -1 on failure.
+ */
 int spdk_sock_group_remove_sock(struct spdk_sock_group *group, struct spdk_sock *sock);
+
+/**
+ * Poll incoming events for each registered socket.
+ *
+ * \param group Group to poll.
+ *
+ * \return 0 on success, -1 on failure.
+ */
 int spdk_sock_group_poll(struct spdk_sock_group *group);
+
+/**
+ * Poll incoming events up to max_events for each registered socket.
+ *
+ * \param group Group to poll.
+ * \param max_events Number of maximum events to poll for each socket.
+ *
+ * \return the number of events on success, -1 on failure.
+ */
 int spdk_sock_group_poll_count(struct spdk_sock_group *group, int max_events);
+
+/**
+ * Close all registered sockets of the group and then remove the group.
+ *
+ * \param group Group to close.
+ *
+ * \return 0 on success, -1 on failure.
+ */
 int spdk_sock_group_close(struct spdk_sock_group **group);
 
 #ifdef __cplusplus