Document Socket API functions return values.

Describe the return values with as much detail as possible, to let user only check the relevant return codes, instead of all nsapi_error_t. Refer to underlying APIs wherever possible.

Author: michalpasztamobica

features/netsocket/TCPSocket.h

@@ -77,7 +77,13 @@ class TCPSocket : public InternetSocket {
      *
      *  @param host     Hostname of the remote host
      *  @param port     Port of the remote host
-     *  @return         0 on success, negative error code on failure
+     *  @retval         NSAPI_ERROR_OK on success
+     *  @retval         NSAPI_ERROR_IN_PROGRESS if the operation is ongoing
+     *  @retval         NSAPI_ERROR_NO_SOCKET if the socket has not been allocated
+     *  @retval         NSAPI_ERROR_DNS_FAILURE if the DNS address of host could not be resolved
+     *  @retval         NSAPI_ERROR_IS_CONNECTED if the connection is already established
+     *  @retval         int Other negative error codes for stack-related failures.
+     *                  See NetworkStack::socket_connect().
      */
     nsapi_error_t connect(const char *host, uint16_t port);
 
@@ -87,7 +93,13 @@ class TCPSocket : public InternetSocket {
      *  indicated address.
      *
      *  @param address  The SocketAddress of the remote host
-     *  @return         0 on success, negative error code on failure
+     *  @retval         NSAPI_ERROR_OK on success
+     *  @retval         NSAPI_ERROR_IN_PROGRESS if the operation is ongoing
+     *  @retval         NSAPI_ERROR_NO_SOCKET if the socket has not been allocated
+     *  @retval         NSAPI_ERROR_DNS_FAILURE if the DNS address of host could not be resolved
+     *  @retval         NSAPI_ERROR_IS_CONNECTED if the connection is already established
+     *  @retval         int Other negative error codes for stack-related failures.
+     *                  See NetworkStack::socket_connect().
      */
     virtual nsapi_error_t connect(const SocketAddress &address);
 
@@ -102,8 +114,12 @@ class TCPSocket : public InternetSocket {
      *
      *  @param data     Buffer of data to send to the host
      *  @param size     Size of the buffer in bytes
-     *  @return         Number of sent bytes on success, negative error
-     *                  code on failure
+     *  @retval         int Number of sent bytes on success
+     *  @retval         NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
+     *  @retval         NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
+     *                  and send cannot be performed immediately
+     *  @retval         int Other negative error codes for stack-related failures.
+     *                  See \ref NetworkStack::socket_send.
      */
     virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size);
 
@@ -118,10 +134,12 @@ class TCPSocket : public InternetSocket {
      *
      *  @param data     Destination buffer for data received from the host
      *  @param size     Size of the buffer in bytes
-     *  @return         Number of received bytes on success, negative error
-     *                  code on failure. If no data is available to be received
-     *                  and the peer has performed an orderly shutdown,
-     *                  recv() returns 0.
+     *  @retval         int Number of received bytes on success
+     *  @retval         NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
+     *  @retval         NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
+     *                  and send cannot be performed immediately
+     *  @retval         int Other negative error codes for stack-related failures.
+     *                  See \ref NetworkStack::socket_recv.
      */
     virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size);
 
@@ -136,8 +154,12 @@ class TCPSocket : public InternetSocket {
      *  @param address  Remote address
      *  @param data     Buffer of data to send to the host
      *  @param size     Size of the buffer in bytes
-     *  @return         Number of sent bytes on success, negative error
-     *                  code on failure
+     *  @retval         int Number of sent bytes on success
+     *  @retval         NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
+     *  @retval         NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
+     *                  and send cannot be performed immediately
+     *  @retval         int Other negative error codes for stack-related failures.
+     *                  See \ref NetworkStack::socket_send.
      */
     virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
                                          const void *data, nsapi_size_t size);
@@ -154,8 +176,12 @@ class TCPSocket : public InternetSocket {
      *  @param address  Destination for the source address or NULL
      *  @param data     Destination buffer for datagram received from the host
      *  @param size     Size of the buffer in bytes
-     *  @return         Number of received bytes on success, negative error
-     *                  code on failure
+     *  @retval         int Number of received bytes on success
+     *  @retval         NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
+     *  @retval         NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
+     *                  and send cannot be performed immediately
+     *  @retval         int Other negative error codes for stack-related failures.
+     *                  See \ref NetworkStack::socket_recv.
      */
     virtual nsapi_size_or_error_t recvfrom(SocketAddress *address,
                                            void *data, nsapi_size_t size);
@@ -182,7 +208,10 @@ class TCPSocket : public InternetSocket {
      *
      *  @param backlog  Number of pending connections that can be queued
      *                  simultaneously, defaults to 1
-     *  @return         0 on success, negative error code on failure
+     *  @retval         NSAPI_ERROR_OK on success
+     *  @retval         NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
+     *  @retval         int Other negative error codes for stack-related failures.
+     *                  See \ref NetworkStack::socket_listen.
      */
     virtual nsapi_error_t listen(int backlog = 1);