update internetsocket docs

Author: paul-szczepanek-arm

features/netsocket/InternetSocket.h

@@ -32,164 +32,150 @@
  */
 class InternetSocket : public Socket {
 public:
-    /** Destroy a socket
+    /** Destroy the socket.
      *
-     *  Closes socket if the socket is still open
+     *  @note Closes socket if it's still open.
      */
     virtual ~InternetSocket() {}
 
-    /** Opens a socket
+    /** Open a network socket on the network stack of the given
+     *  network interface.
      *
-     *  Creates a network socket on the network stack of the given
-     *  network interface. Not needed if stack is passed to the
-     *  socket's constructor.
+     *  @note Not needed if stack is passed to the socket's constructor.
      *
-     *  @param stack    Network stack as target for socket
-     *  @return         0 on success, negative error code on failure
+     *  @param stack    Network stack as target for socket.
+     *  @return         0 on success, negative error code on failure (@see nsapi_types.h).
      */
     nsapi_error_t open(NetworkStack *stack);
 
+#if !defined(DOXYGEN_ONLY)
     template <typename S>
     nsapi_error_t open(S *stack)
     {
         return open(nsapi_create_stack(stack));
     }
+#endif //!defined(DOXYGEN_ONLY)
 
-    /** Close the socket
-     *
-     *  Closes any open connection and deallocates any memory associated
+    /** Close any open connection and deallocate any memory associated
      *  with the socket. Called from destructor if socket is not closed.
      *
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success, negative error code on failure (@see nsapi_types.h).
      */
     virtual nsapi_error_t close();
 
-    /** Subscribes to an IP multicast group
+    /** Subscribe to an IP multicast group.
      *
-     * @param address   Multicast group IP address
-     * @return          Negative error code on failure
+     * @param address   Multicast group IP address.
+     *  @return         0 on success, negative error code on failure (@see nsapi_types.h).
      */
     int join_multicast_group(const SocketAddress &address);
 
-    /** Leave an IP multicast group
+    /** Leave an IP multicast group.
      *
-     * @param address   Multicast group IP address
-     * @return          Negative error code on failure
+     * @param address   Multicast group IP address.
+     *  @return         0 on success, negative error code on failure (@see nsapi_types.h).
      */
     int leave_multicast_group(const SocketAddress &address);
 
-
-    /** Bind a specific address to a socket
-     *
-     *  Binding a socket specifies the address and port on which to receive
-     *  data.
+    /** Bind the socket to a port on which to receive data.
      *
-     *  @param port     Local port to bind
-     *  @return         0 on success, negative error code on failure.
+     *  @param port     Local port to bind.
+     *  @return         0 on success, negative error code on failure (@see nsapi_types.h).
      */
     nsapi_error_t bind(uint16_t port);
 
-    /** Bind a specific address to a socket
-     *
-     *  Binding a socket specifies the address and port on which to receive
-     *  data. If the IP address is zeroed, only the port is bound.
+    /** Bind the socket to a specific address and port on which to receive
+     *  data. If the IP address is zeroed only the port is bound.
      *
-     *  @param address  Null-terminated local address to bind
-     *  @param port     Local port to bind
-     *  @return         0 on success, negative error code on failure.
+     *  @param address  Null-terminated local address to bind.
+     *  @param port     Local port to bind.
+     *  @return         0 on success, negative error code on failure (@see nsapi_types.h).
      */
     nsapi_error_t bind(const char *address, uint16_t port);
 
-    /** Bind a specific address to a socket
-     *
-     *  Binding a socket specifies the address and port on which to receive
+    /** Bind the socket to a specific address and port on which to receive
      *  data. If the IP address is zeroed, only the port is bound.
      *
-     *  @param address  Local address to bind
-     *  @return         0 on success, negative error code on failure.
+     *  @param address  Local SocketAddress to bind which includes the address and port.
+     *  @return         0 on success, negative error code on failure (@see nsapi_types.h).
      */
     virtual nsapi_error_t bind(const SocketAddress &address);
 
-    /** Set blocking or non-blocking mode of the socket
+    /** Set blocking or non-blocking mode of the socket.
      *
      *  Initially all sockets are in blocking mode. In non-blocking mode
      *  blocking operations such as send/recv/accept return
      *  NSAPI_ERROR_WOULD_BLOCK if they can not continue.
      *
-     *  set_blocking(false) is equivalent to set_timeout(-1)
-     *  set_blocking(true) is equivalent to set_timeout(0)
+     *  @note set_blocking(false) is equivalent to set_timeout(-1) and
+     *  set_blocking(true) is equivalent to set_timeout(0).
      *
-     *  @param blocking true for blocking mode, false for non-blocking mode.
+     *  @param blocking Use true for blocking mode, false for non-blocking mode.
      */
     virtual void set_blocking(bool blocking);
 
-    /** Set timeout on blocking socket operations
+    /** Set timeout on blocking socket operations.
      *
      *  Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
      *  is returned if a blocking operation takes longer than the specified
      *  timeout. A timeout of 0 removes the timeout from the socket. A negative
      *  value give the socket an unbounded timeout.
      *
-     *  set_timeout(0) is equivalent to set_blocking(false)
-     *  set_timeout(-1) is equivalent to set_blocking(true)
+     *  @note set_timeout(0) is equivalent to set_blocking(false) and
+     *  set_timeout(-1) is equivalent to set_blocking(true).
      *
-     *  @param timeout  Timeout in milliseconds
+     *  @param timeout  Timeout in milliseconds.
      */
     virtual void set_timeout(int timeout);
 
-    /*  Set socket options
-     *
-     *  setsockopt allows an application to pass stack-specific options
-     *  to the underlying stack using stack-specific level and option names,
-     *  or to request generic options using levels from nsapi_socket_level_t.
+    /** Pass stack-specific options to the underlying stack using stack-specific
+     *  level and option names, or request generic options using levels from nsapi_socket_level_t.
      *
      *  For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
      *  and the socket is unmodified.
      *
-     *  @param level    Stack-specific protocol level or nsapi_socket_level_t
-     *  @param optname  Level-specific option name
-     *  @param optval   Option value
-     *  @param optlen   Length of the option value
-     *  @return         0 on success, negative error code on failure
+     *  @param level    Stack-specific protocol level or nsapi_socket_level_t.
+     *  @param optname  Level-specific option name.
+     *  @param optval   Option value.
+     *  @param optlen   Length of the option value.
+     *  @return         0 on success, negative error code on failure (@see nsapi_types.h).
      */
     virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen);
 
-    /*  Get socket options
-     *
-     *  getsockopt allows an application to retrieve stack-specific options
-     *  from the underlying stack using stack-specific level and option names,
-     *  or to request generic options using levels from nsapi_socket_level_t.
+    /** Retrieve stack-specific options from the underlying stack using
+     *  stack-specific level and option names, or request generic options
+     *  using levels from nsapi_socket_level_t.
      *
      *  For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
      *  and the socket is unmodified.
      *
-     *  @param level    Stack-specific protocol level or nsapi_socket_level_t
-     *  @param optname  Level-specific option name
-     *  @param optval   Destination for option value
-     *  @param optlen   Length of the option value
-     *  @return         0 on success, negative error code on failure
+     *  @param level    Stack-specific protocol level or nsapi_socket_level_t.
+     *  @param optname  Level-specific option name.
+     *  @param optval   Destination for option value.
+     *  @param optlen   Length of the option value.
+     *  @return         0 on success, negative error code on failure (@see nsapi_types.h).
      */
     virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen);
 
-    /** Register a callback on state change of the socket
+    /** Register a callback on state change of the socket.
      *
      *  The specified callback will be called on state changes such as when
-     *  the socket can recv/send/accept successfully and on when an error
-     *  occurs. The callback may also be called spuriously without reason.
+     *  the socket can recv/send/accept successfully and when an error
+     *  occurs. The callback may also be called spuriously without a reason.
      *
      *  The callback may be called in an interrupt context and should not
      *  perform expensive operations such as recv/send calls.
      *
-     *  Note! This is not intended as a replacement for a poll or attach-like
-     *  asynchronous api, but rather as a building block for constructing
+     *  @note This is not intended as a replacement for a poll or attach-like
+     *  asynchronous API, but rather as a building block for constructing
      *  such functionality. The exact timing of when the registered function
-     *  is called is not guaranteed and susceptible to change.
+     *  is called is not guaranteed and is susceptible to change.
      *
-     *  @param func     Function to call on state change
+     *  @param func     Function to call on state change.
      */
     virtual void sigio(mbed::Callback<void()> func);
 
-    /** Register a callback on state change of the socket
+    /** Register a callback on state change of the socket.
      *
      *  @see Socket::sigio
      *  @deprecated
@@ -201,7 +187,7 @@ class InternetSocket : public Socket {
                           "mbed OS and has been known to cause confusion. Replaced by Socket::sigio.")
     void attach(mbed::Callback<void()> func);
 
-    /** Register a callback on state change of the socket
+    /** Register a callback on state change of the socket.
      *
      *  @see Socket::sigio
      *  @deprecated
@@ -217,6 +203,8 @@ class InternetSocket : public Socket {
         attach(mbed::callback(obj, method));
     }
 
+#if !defined(DOXYGEN_ONLY)
+
 protected:
     InternetSocket();
     virtual nsapi_protocol_t get_proto() = 0;
@@ -240,6 +228,8 @@ class InternetSocket : public Socket {
     static const int READ_FLAG     = 0x1u;
     static const int WRITE_FLAG    = 0x2u;
     static const int FINISHED_FLAG = 0x3u;
+
+#endif //!defined(DOXYGEN_ONLY)
 };
 
 #endif // INTERNETSOCKET_H

features/netsocket/Socket.h

@@ -194,7 +194,7 @@ class Socket {
      */
     virtual void sigio(mbed::Callback<void()> func) = 0;
 
-    /*  Set socket options.
+    /** Set socket options.
      *
      *  setsockopt() allows an application to pass stack-specific options
      *  to the underlying stack using stack-specific level and option names,
@@ -211,7 +211,7 @@ class Socket {
      */
     virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0;
 
-    /*  Get socket options.
+    /** Get socket options.
      *
      *  getsockopt() allows an application to retrieve stack-specific options
      *  from the underlying stack using stack-specific level and option names,