doxy cleanup

Author: paul-szczepanek-arm

features/netsocket/UDPSocket.h

@@ -26,119 +26,106 @@
 #include "rtos/EventFlags.h"
 
 
-/** UDP socket
+/** UDP socket implementation.
  */
 class UDPSocket : public InternetSocket {
 public:
-    /** Create an uninitialized socket
+    /** Create an uninitialized socket.
      *
-     *  Must call open to initialize the socket on a network stack.
+     *  @note Must call open to initialize the socket on a network stack.
      */
     UDPSocket();
 
-    /** Create a socket on a network interface
-     *
-     *  Creates and opens a socket on the network stack of the given
+    /** Create and open a socket on the network stack of the given
      *  network interface.
      *
-     *  @param stack    Network stack as target for socket
+     *  @tparam S    Type of the Network stack.
+     *  @param stack Network stack as target for socket.
      */
     template <typename S>
     UDPSocket(S *stack)
     {
         open(stack);
     }
 
-    /** Destroy a socket
+    /** Destroy a socket.
      *
-     *  Closes socket if the socket is still open
+     *  @note Closes socket if the socket is still open.
      */
     virtual ~UDPSocket();
 
-    /** Send a packet over a UDP socket
-     *
-     *  Sends data to the specified address specified by either a domain name
-     *  or an IP address and port. Returns the number of bytes sent from the
-     *  buffer.
+    /** Send data to the specified host and port.
      *
      *  By default, sendto blocks until data is sent. If socket is set to
      *  non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
      *  immediately.
      *
-     *  @param host     Hostname of the remote host
-     *  @param port     Port of the remote host
-     *  @param data     Buffer of data to send to the host
-     *  @param size     Size of the buffer in bytes
+     *  @param host     Domain name of the remote host or a dotted notation IP address.
+     *  @param port     Port of the remote host.
+     *  @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
+     *                  code on failure.
      */
     virtual nsapi_size_or_error_t sendto(const char *host, uint16_t port,
                                          const void *data, nsapi_size_t size);
 
-    /** Send a packet over a UDP socket
-     *
-     *  Sends data to the specified address. Returns the number of bytes
-     *  sent from the buffer.
+    /** Send data to the specified address.
      *
      *  By default, sendto blocks until data is sent. If socket is set to
      *  non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
      *  immediately.
      *
-     *  @param address  The SocketAddress of the remote host
-     *  @param data     Buffer of data to send to the host
-     *  @param size     Size of the buffer in bytes
+     *  @param address  The SocketAddress of the remote host.
+     *  @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
+     *                  code on failure.
      */
     virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
                                          const void *data, nsapi_size_t size);
 
-    /** Receive a datagram over a UDP socket
+    /** Receive a datagram and store the source address in address if it's not NULL.
+     *
+     *  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.
      *
-     *  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.
+     *  @note If the datagram is larger than the buffer, the excess data is silently discarded.
      *
-     *  If socket is connected, only packets coming from connected peer address
+     *  @note If socket is connected, only packets coming from connected peer address
      *  are accepted.
      *
      *  @note recvfrom() is allowed write to address and data buffers even if error occurs.
      *
-     *  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 datagram received from the host
-     *  @param size     Size of the buffer in bytes
+     *  @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
+     *                  code on failure.
      */
     virtual nsapi_size_or_error_t recvfrom(SocketAddress *address,
                                            void *data, nsapi_size_t size);
 
-    /** Set remote peer address
-     *
-     *  Set the remote address for next send() call and filtering
-     *  for incomming packets. To reset the address, zero initialised
+    /** Set the remote address for next send() call and filtering
+     *  of incoming packets. To reset the address, zero initialised
      *  SocketAddress must be in the address parameter.
      *
-     *  @param address  The SocketAddress of the remote host
-     *  @return         0 on success, negative error code on failure
+     *  @param address  The SocketAddress of the remote host.
+     *  @return         0 on success, negative error code on failure.
      */
     virtual nsapi_error_t connect(const SocketAddress &address);
 
-    /** Send a datagram to pre-specified remote.
-     *
-     *  The socket must be connected to a remote host before send() call.
-     *  Returns the number of bytes sent from the buffer.
+    /** Send a datagram to connected remote address.
      *
      *  By default, send blocks until all data is sent. If socket is set to
      *  non-blocking or times out, a partial amount can be written.
      *  NSAPI_ERROR_WOULD_BLOCK is returned if no data was written.
      *
-     *  @param data     Buffer of data to send to the host
-     *  @param size     Size of the buffer in bytes
+     *  @note The socket must be connected to a remote host before send() call.
+     *
+     *  @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.
      */
@@ -151,35 +138,39 @@ class UDPSocket : public InternetSocket {
      *  If socket is connected, only packets coming from connected peer address
      *  are accepted.
      *
-     *  @note recv() is allowed write to data buffer even if error occurs.
-     *
      *  By default, recv blocks until some data is received. If socket is set to
      *  non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to
      *  indicate no data.
      *
-     *  @param data     Destination buffer for data received from the host
-     *  @param size     Size of the buffer in bytes
+     *  @note recv() is allowed write to data buffer even if error occurs.
+     *
+     *  @param data     Pointer to 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.
      */
     virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size);
 
-    /** Not implemented for UDP
+    /** Not implemented for UDP.
      *
-     *  @param error      unused
+     *  @param error      Not used.
      *  @return           NSAPI_ERROR_UNSUPPORTED
      */
     virtual Socket *accept(nsapi_error_t *error = NULL);
 
-    /** Not implemented for UDP
+    /** Not implemented for UDP.
      *
-     *  @param backlog    unused
+     *  @param backlog    Not used.
      *  @return           NSAPI_ERROR_UNSUPPORTED
      */
     virtual nsapi_error_t listen(int backlog = 1);
 
+#if !defined(DOXYGEN_ONLY)
+
 protected:
     virtual nsapi_protocol_t get_proto();
+
+#endif //!defined(DOXYGEN_ONLY)
 };