Merge pull request #5623 from SeppoTakalo/clarify_socket_docs

Clarify TCPSocket::recv() and UDPSocket::recvfrom() documentation.

Author: 0xc0170

features/netsocket/TCPSocket.h

@@ -111,7 +111,9 @@ class TCPSocket : public Socket {
      *  @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
+     *                  code on failure. If no data is available to be received
+     *                  and the peer has performed an orderly shutdown,
+     *                  recv() returns 0.
      */
     nsapi_size_or_error_t recv(void *data, nsapi_size_t size);
 

features/netsocket/UDPSocket.h

@@ -94,17 +94,18 @@ class UDPSocket : public Socket {
     nsapi_size_or_error_t sendto(const SocketAddress &address,
             const void *data, nsapi_size_t size);
 
-    /** Receive a packet over a UDP socket
+    /** Receive a datagram over a UDP socket
      *
-     *  Receives data and stores the source address in address if address
-     *  is not NULL. Returns the number of bytes received into the buffer.
+     *  Receives a datagram and stores the source address in address if address
+     *  is not NULL. Returns the number of bytes written into the buffer. If the
+     *  datagram is larger than the buffer, the excess data is silently discarded.
      *
-     *  By default, recvfrom blocks until data is sent. If socket is set to
-     *  non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
-     *  immediately.
+     *  By default, recvfrom blocks until a datagram is received. If socket is set to
+     *  non-blocking or times out with no datagram, NSAPI_ERROR_WOULD_BLOCK
+     *  is returned.
      *
      *  @param address  Destination for the source address or NULL
-     *  @param data     Destination buffer for data received from the host
+     *  @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