diff --git a/components/wifi/esp8266-driver/ESP8266Interface.h b/components/wifi/esp8266-driver/ESP8266Interface.h
index 4d19dd60e75..a8dae7bb988 100644
--- a/components/wifi/esp8266-driver/ESP8266Interface.h
+++ b/components/wifi/esp8266-driver/ESP8266Interface.h
@@ -153,36 +153,12 @@ class ESP8266Interface : public NetworkStack, public WiFiInterface
      */
     using NetworkInterface::add_dns_server;
 
-    /** Set socket options
-     *
-     *  The setsockopt allow an application to pass stack-specific hints
-     *  to the underlying stack. For unsupported options,
-     *  NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
-     *
-     *  @param handle   Socket handle
-     *  @param level    Stack-specific protocol level
-     *  @param optname  Stack-specific option identifier
-     *  @param optval   Option value
-     *  @param optlen   Length of the option value
-     *  @return         0 on success, negative error code on failure
+    /** @copydoc NetworkStack::setsockopt
      */
     virtual nsapi_error_t setsockopt(nsapi_socket_t handle, 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.
-     *
-     *  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
+    /** @copydoc NetworkStack::getsockopt
      */
     virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, int optname,
             void *optval, unsigned *optlen);
diff --git a/features/netsocket/CellularBase.h b/features/netsocket/CellularBase.h
index 348324020bf..26377a8d3b9 100644
--- a/features/netsocket/CellularBase.h
+++ b/features/netsocket/CellularBase.h
@@ -18,115 +18,114 @@
 
 #include "netsocket/NetworkInterface.h"
 
-/** CellularBase class
- *
- *  Common interface that is shared between Cellular interfaces
+/** Common interface that is shared between cellular interfaces.
+ *  @addtogroup netsocket
  */
 class CellularBase: public NetworkInterface {
 
 public:
-
-    /** Get the default Cellular interface.
+    /** Get the default cellular interface.
      *
      * This is provided as a weak method so applications can override.
      * Default behaviour is to get the target's default interface, if
      * any.
      *
-     * @return pointer to interface, if any
+     * @return pointer to interface, if any.
      */
-
     static CellularBase *get_default_instance();
 
-    /** Set the Cellular network credentials
+    /** Set the cellular network credentials.
      *
      *  Please check documentation of connect() for default behaviour of APN settings.
      *
-     *  @param apn      Access point name
-     *  @param uname    optionally, Username
-     *  @param pwd      optionally, password
+     *  @param apn      Access point name.
+     *  @param uname    Username (optional).
+     *  @param pwd      Password (optional).
      */
     virtual void set_credentials(const char *apn, const char *uname = 0,
                                  const char *pwd = 0) = 0;
 
-    /** Set the pin code for SIM card
+    /** Set the PIN code for SIM card.
      *
-     *  @param sim_pin      PIN for the SIM card
+     *  @param sim_pin      PIN for the SIM card.
      */
     virtual void set_sim_pin(const char *sim_pin) = 0;
 
-    /** Start the interface
-     *
-     *  Attempts to connect to a Cellular network.
+    /** Attempt to connect to a cellular network with a PIN and credentials.
      *
-     *  @param sim_pin     PIN for the SIM card
-     *  @param apn         optionally, access point name
-     *  @param uname       optionally, Username
-     *  @param pwd         optionally, password
-     *  @return            NSAPI_ERROR_OK on success, or negative error code on failure
+     *  @param sim_pin     PIN for the SIM card.
+     *  @param apn         Access point name (optional).
+     *  @param uname       Username (optional).
+     *  @param pwd         Password (optional).
+     *  @return            NSAPI_ERROR_OK on success, or negative error code on failure.
      */
     virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0,
                                   const char *uname = 0,
                                   const char *pwd = 0) = 0;
 
-    /** Start the interface
+    /** Attempt to connect to a cellular network.
      *
-     *  Attempts to connect to a Cellular network.
-     *  If the SIM requires a PIN, and it is not set/invalid, NSAPI_ERROR_AUTH_ERROR is returned.
+     *  If the SIM requires a PIN, and it is invalid or not set, NSAPI_ERROR_AUTH_ERROR is returned.
      *
-     *  @return            NSAPI_ERROR_OK on success, or negative error code on failure
+     *  @return         NSAPI_ERROR_OK on success, or negative error code on failure.
      */
     virtual nsapi_error_t connect() = 0;
 
-    /** Stop the interface
+    /** Stop the interface.
      *
-     *  @return         0 on success, or error code on failure
+     *  @return         NSAPI_ERROR_OK on success, or error code on failure.
      */
     virtual nsapi_error_t disconnect() = 0;
 
-    /** Check if the connection is currently established or not
+    /** Check if the connection is currently established.
      *
-     * @return true/false   If the cellular module have successfully acquired a carrier and is
-     *                      connected to an external packet data network using PPP, isConnected()
-     *                      API returns true and false otherwise.
+     * @return `true` if the cellular module have successfully acquired a carrier and is
+     *         connected to an external packet data network using PPP, `false` otherwise.
      */
     virtual bool is_connected() = 0;
 
-    /** Get the local IP address
+    /** Get the local IP address.
      *
-     *  @return         Null-terminated representation of the local IP address
-     *                  or null if no IP address has been received
+     *  @return         Null-terminated representation of the local IP address,
+     *                  or null if no IP address has been received.
      */
     virtual const char *get_ip_address() = 0;
 
-    /** Get the local network mask
+    /** Get the local network mask.
      *
-     *  @return         Null-terminated representation of the local network mask
-     *                  or null if no network mask has been received
+     *  @return         Null-terminated representation of the local network mask,
+     *                  or null if no network mask has been received.
      */
     virtual const char *get_netmask() = 0;
 
-    /** Get the local gateways
+    /** Get the local gateways.
      *
-     *  @return         Null-terminated representation of the local gateway
-     *                  or null if no network mask has been received
+     *  @return         Null-terminated representation of the local gateway,
+     *                  or null if no network mask has been received.
      */
     virtual const char *get_gateway() = 0;
 
+    /** @copydoc NetworkInterface::cellularBase
+     */
     virtual CellularBase *cellularBase()
     {
         return this;
     }
 
+#if !defined(DOXYGEN_ONLY)
+
 protected:
-    /** Get the target's default Cellular interface.
+    /** Get the target's default cellular interface.
      *
      * This is provided as a weak method so targets can override. The
-     * default implementation configures and returns the OnBoardModemInterface
+     * default implementation configures and returns the OnBoardModemInterface,
      * if available.
      *
-     * @return pointer to interface, if any
+     * @return Pointer to interface, if any.
      */
     static CellularBase *get_target_default_instance();
+
+#endif //!defined(DOXYGEN_ONLY)
 };
 
 #endif //CELLULAR_BASE_H
diff --git a/features/netsocket/DNS.h b/features/netsocket/DNS.h
index 9e74744b6b4..bdfa69705f2 100644
--- a/features/netsocket/DNS.h
+++ b/features/netsocket/DNS.h
@@ -20,7 +20,7 @@
 class DNS {
 public:
 
-    /** Translates a hostname to an IP address with specific version
+    /** Translate a hostname to an IP address with specific version.
      *
      *  The hostname may be either a domain name or an IP address. If the
      *  hostname is an IP address, no network transactions will be performed.
@@ -28,18 +28,18 @@ class DNS {
      *  If no stack-specific DNS resolution is provided, the hostname
      *  will be resolve using a UDP socket on the stack.
      *
-     *  @param host     Hostname to resolve
-     *  @param address  Destination for the host SocketAddress
+     *  @param host     Hostname to resolve.
+     *  @param address  Pointer to a SocketAddress to store the result.
      *  @param version  IP version of address to resolve, NSAPI_UNSPEC indicates
-     *                  version is chosen by the stack (defaults to NSAPI_UNSPEC)
-     *  @return         0 on success, negative error code on failure
+     *                  version is chosen by the stack (defaults to NSAPI_UNSPEC).
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t gethostbyname(const char *host,
                                         SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC) = 0;
 
-    /** Hostname translation callback (asynchronous)
+    /** Hostname translation callback for gethostbyname_async.
      *
-     *  Callback will be called after DNS resolution completes or a failure occurs.
+     *  The callback is called after DNS resolution completes, or a failure occurs.
      *
      *  Callback should not take more than 10ms to execute, otherwise it might
      *  prevent underlying thread processing. A portable user of the callback
@@ -47,49 +47,49 @@ class DNS {
      *  The callback should not perform expensive operations such as socket recv/send
      *  calls or blocking operations.
      *
-     *  @param status  0 on success, negative error code on failure
-     *  @param address On success, destination for the host SocketAddress
+     *  @param result  NSAPI_ERROR_OK on success, negative error code on failure.
+     *  @param address On success, destination for the host SocketAddress.
      */
     typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t;
 
-    /** Translates a hostname to an IP address (asynchronous)
+    /** Translate a hostname to an IP address (asynchronous).
      *
      *  The hostname may be either a domain name or an IP address. If the
      *  hostname is an IP address, no network transactions will be performed.
      *
      *  If no stack-specific DNS resolution is provided, the hostname
-     *  will be resolve using a UDP socket on the stack.
+     *  will be resolved using a UDP socket on the stack.
      *
-     *  Call is non-blocking. Result of the DNS operation is returned by the callback.
-     *  If this function returns failure, callback will not be called. In case result
-     *  is success (IP address was found from DNS cache), callback will be called
-     *  before function returns.
+     *  The call is non-blocking. The result of the DNS operation is returned by the callback.
+     *  If this function returns failure, the callback will not be called. If it is successful,
+     *  (the IP address was found from the DNS cache), the callback will be called
+     *  before the function returns.
      *
-     *  @param host     Hostname to resolve
-     *  @param callback Callback that is called for result
-     *  @param version  IP version of address to resolve, NSAPI_UNSPEC indicates
-     *                  version is chosen by the stack (defaults to NSAPI_UNSPEC)
-     *  @return         0 on immediate success,
+     *  @param host     Hostname to resolve.
+     *  @param callback Callback that is called to return the result.
+     *  @param version  IP version of address to resolve. NSAPI_UNSPEC indicates that the
+     *                  version is chosen by the stack (defaults to NSAPI_UNSPEC).
+     *  @return         NSAPI_ERROR_OK on immediate success,
      *                  negative error code on immediate failure or
-     *                  a positive unique id that represents the hostname translation operation
-     *                  and can be passed to cancel
+     *                  a positive unique ID that represents the hostname translation operation
+     *                  and can be passed to cancel.
      */
     virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback,
                                                        nsapi_version_t version = NSAPI_UNSPEC) = 0;
 
-    /** Cancels asynchronous hostname translation
+    /** Cancel asynchronous hostname translation.
      *
-     *  When translation is cancelled, callback will not be called.
+     *  When translation is canceled, callback is not called.
      *
-     *  @param id       Unique id of the hostname translation operation
-     *  @return         0 on success, negative error code on failure
+     *  @param id       Unique ID of the hostname translation operation returned by gethostbyname_async.
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t gethostbyname_async_cancel(int id) = 0;
 
-    /** Add a domain name server to list of servers to query
+    /** Add a domain name server to list of servers to query.
      *
-     *  @param address  Destination for the host address
-     *  @return         0 on success, negative error code on failure
+     *  @param address  DNS server host address.
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t add_dns_server(const SocketAddress &address) = 0;
 };
diff --git a/features/netsocket/EthInterface.h b/features/netsocket/EthInterface.h
index ed7a0de8181..af739efe5b5 100644
--- a/features/netsocket/EthInterface.h
+++ b/features/netsocket/EthInterface.h
@@ -23,13 +23,13 @@
 #include "netsocket/NetworkInterface.h"
 
 
-/** EthInterface class
- *
- *  Common interface that is shared between ethernet hardware.
+/** Common interface that is shared between Ethernet hardware.
  */
 class EthInterface : public virtual NetworkInterface {
 public:
 
+    /** @copydoc NetworkInterface::ethInterface
+     */
     virtual EthInterface *ethInterface()
     {
         return this;
@@ -41,10 +41,11 @@ class EthInterface : public virtual NetworkInterface {
      * Default behaviour is to get the target's default interface, if
      * any.
      *
-     * @return pointer to interface, if any
+     * @return Pointer to interface, if one exists.
      */
     static EthInterface *get_default_instance();
 
+#if !defined(DOXYGEN_ONLY)
 protected:
 
     /** Get the target's default Ethernet interface.
@@ -53,9 +54,10 @@ class EthInterface : public virtual NetworkInterface {
      * default implementation will invoke EthernetInterface with the
      * default EMAC and default network stack, if DEVICE_EMAC is set.
      *
-     * @return pointer to interface, if any
+     * @return Pointer to interface, if one exists.
      */
     static EthInterface *get_target_default_instance();
+#endif //!defined(DOXYGEN_ONLY)
 };
 
 
diff --git a/features/netsocket/EthernetInterface.h b/features/netsocket/EthernetInterface.h
index 616419baa27..08b158dd499 100644
--- a/features/netsocket/EthernetInterface.h
+++ b/features/netsocket/EthernetInterface.h
@@ -21,12 +21,11 @@
 #include "EMACInterface.h"
 
 
-/** EthernetInterface class
- *  Implementation of the NetworkStack for an EMAC-based Ethernet driver
+/** Implementation of the NetworkStack for an EMAC-based Ethernet driver.
  */
 class EthernetInterface : public EMACInterface, public EthInterface {
 public:
-    /** Create an EMAC-based ethernet interface.
+    /** Create an EMAC-based Ethernet interface.
      *
      * The default arguments obtain the default EMAC, which will be target-
      * dependent (and the target may have some JSON option to choose which
@@ -36,8 +35,8 @@ class EthernetInterface : public EMACInterface, public EthInterface {
      * Due to inability to return errors from the constructor, no real
      * work is done until the first call to connect().
      *
-     * @param emac  Reference to EMAC to use
-     * @param stack Reference to onboard-network stack to use
+     * @param emac  Reference to EMAC to use.
+     * @param stack Reference to onboard-network stack to use.
      */
     EthernetInterface(EMAC &emac = EMAC::get_default_instance(),
                       OnboardNetworkStack &stack = OnboardNetworkStack::get_default_instance()) : EMACInterface(emac, stack) { }
diff --git a/features/netsocket/InternetSocket.h b/features/netsocket/InternetSocket.h
index 511ff34b247..8294fa1912c 100644
--- a/features/netsocket/InternetSocket.h
+++ b/features/netsocket/InternetSocket.h
@@ -100,92 +100,27 @@ class InternetSocket : public Socket {
      */
     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
-     *  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.
+    /** @copydoc Socket::bind
      */
     virtual nsapi_error_t bind(const SocketAddress &address);
 
-    /** 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)
-     *
-     *  @param blocking true for blocking mode, false for non-blocking mode.
+    /** @copydoc Socket::set_blocking
      */
     virtual void set_blocking(bool blocking);
 
-    /** 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)
-     *
-     *  @param timeout  Timeout in milliseconds
+    /** @copydoc Socket::set_timeout
      */
     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.
-     *
-     *  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
+    /** @copydoc Socket::setsockopt
      */
     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.
-     *
-     *  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
+    /** @copydoc Socket::getsockopt
      */
     virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen);
 
-    /** 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 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
-     *  such functionality. The exact timing of when the registered function
-     *  is called is not guaranteed and susceptible to change.
-     *
-     *  @param func     Function to call on state change
+    /** @copydoc Socket::sigio
      */
     virtual void sigio(mbed::Callback<void()> func);
 
diff --git a/features/netsocket/MeshInterface.h b/features/netsocket/MeshInterface.h
index e6f4efb6731..0dac75098c1 100644
--- a/features/netsocket/MeshInterface.h
+++ b/features/netsocket/MeshInterface.h
@@ -23,13 +23,12 @@
 #include "netsocket/NetworkInterface.h"
 
 
-/** MeshInterface class
- *
- *  Common interface that is shared between mesh hardware
+/** Common interface that is shared between mesh hardware
  */
 class MeshInterface : public virtual NetworkInterface {
 public:
-
+    /** @copydoc NetworkInterface::meshInterface
+     */
     virtual MeshInterface *meshInterface()
     {
         return this;
@@ -41,10 +40,11 @@ class MeshInterface : public virtual NetworkInterface {
      * Default behaviour is to get the target's default interface, if
      * any.
      *
-     * @return pointer to interface, if any
+     * @return pointer to interface, if any.
      */
     static MeshInterface *get_default_instance();
 
+#if !defined(DOXYGEN_ONLY)
 protected:
 
     /** Get the target's default Mesh interface.
@@ -53,9 +53,10 @@ class MeshInterface : public virtual NetworkInterface {
      * default implementation will invoke LoWPANNDInterface or ThreadInterface
      * with the default NanostackRfPhy.
      *
-     * @return pointer to interface, if any
+     * @return pointer to interface, if any.
      */
     static MeshInterface *get_target_default_instance();
+#endif //!defined(DOXYGEN_ONLY)
 };
 
 
diff --git a/features/netsocket/NetworkInterface.h b/features/netsocket/NetworkInterface.h
index 7eb674df13e..2c357a57a13 100644
--- a/features/netsocket/NetworkInterface.h
+++ b/features/netsocket/NetworkInterface.h
@@ -31,9 +31,8 @@ class MeshInterface;
 class CellularBase;
 class EMACInterface;
 
-/** NetworkInterface class
+/** Common interface that is shared between network devices.
  *
- *  Common interface that is shared between network devices
  *  @addtogroup netsocket
  */
 class NetworkInterface: public DNS {
@@ -41,13 +40,14 @@ class NetworkInterface: public DNS {
 
     virtual ~NetworkInterface() {};
 
-    /** Return the default network interface
+    /** Return the default network interface.
      *
      * Returns the default network interface, as determined by JSON option
      * target.network-default-interface-type or other overrides.
      *
-     * The type of the interface returned can be tested via the ethInterface()
-     * etc downcasts.
+     * The type of the interface returned can be tested by calling ethInterface(),
+     * wifiInterface(), meshInterface(), cellularBase(), emacInterface() and checking
+     * for NULL pointers.
      *
      * The default behaviour is to return the default interface for the
      * interface type specified by target.network-default-interface-type. Targets
@@ -79,75 +79,72 @@ class NetworkInterface: public DNS {
      */
     static NetworkInterface *get_default_instance();
 
-    /** Get the local MAC address
+    /** Get the local MAC address.
      *
      *  Provided MAC address is intended for info or debug purposes and
-     *  may not be provided if the underlying network interface does not
-     *  provide a MAC address
+     *  may be not provided if the underlying network interface does not
+     *  provide a MAC address.
      *
      *  @return         Null-terminated representation of the local MAC address
-     *                  or null if no MAC address is available
+     *                  or null if no MAC address is available.
      */
     virtual const char *get_mac_address();
 
-    /** Get the local IP address
+    /** Get the local IP address.
      *
      *  @return         Null-terminated representation of the local IP address
-     *                  or null if no IP address has been received
+     *                  or null if no IP address has been received.
      */
     virtual const char *get_ip_address();
 
-    /** Get the local network mask
+    /** Get the local network mask.
      *
      *  @return         Null-terminated representation of the local network mask
-     *                  or null if no network mask has been received
+     *                  or null if no network mask has been received.
      */
     virtual const char *get_netmask();
 
-    /** Get the local gateway
+    /** Get the local gateway.
      *
      *  @return         Null-terminated representation of the local gateway
-     *                  or null if no network mask has been received
+     *                  or null if no network mask has been received.
      */
     virtual const char *get_gateway();
 
-    /** Set a static IP address
-     *
-     *  Configures this network interface to use a static IP address.
+    /** Configure this network interface to use a static IP address.
      *  Implicitly disables DHCP, which can be enabled in set_dhcp.
      *  Requires that the network is disconnected.
      *
      *  @param ip_address Null-terminated representation of the local IP address
      *  @param netmask    Null-terminated representation of the local network mask
      *  @param gateway    Null-terminated representation of the local gateway
-     *  @return           0 on success, negative error code on failure
+     *  @return           NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t set_network(const char *ip_address, const char *netmask, const char *gateway);
 
-    /** Enable or disable DHCP on the network
+    /** Enable or disable DHCP on connecting the network.
      *
-     *  Enables DHCP on connecting the network. Defaults to enabled unless
-     *  a static IP address has been assigned. Requires that the network is
-     *  disconnected.
+     *  Enabled by default unless a static IP address has been assigned. Requires
+     *  that the network is disconnected.
      *
-     *  @param dhcp     True to enable DHCP
-     *  @return         0 on success, negative error code on failure
+     *  @param dhcp     True to enable DHCP.
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t set_dhcp(bool dhcp);
 
-    /** Start the interface
+    /** Start the interface.
      *
-     *  @return     0 on success, negative error code on failure
+     *  @return     NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t connect() = 0;
 
-    /** Stop the interface
+    /** Stop the interface.
      *
-     *  @return     0 on success, negative error code on failure
+     *  @return     NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t disconnect() = 0;
 
-    /** Translates a hostname to an IP address with specific version
+    /** Translate a hostname to an IP address with specific version.
      *
      *  The hostname may be either a domain name or an IP address. If the
      *  hostname is an IP address, no network transactions will be performed.
@@ -155,33 +152,33 @@ class NetworkInterface: public DNS {
      *  If no stack-specific DNS resolution is provided, the hostname
      *  will be resolve using a UDP socket on the stack.
      *
-     *  @param host     Hostname to resolve
-     *  @param address  Destination for the host SocketAddress
+     *  @param host     Hostname to resolve.
+     *  @param address  Pointer to a SocketAddress to store the result.
      *  @param version  IP version of address to resolve, NSAPI_UNSPEC indicates
-     *                  version is chosen by the stack (defaults to NSAPI_UNSPEC)
-     *  @return         0 on success, negative error code on failure
+     *                  version is chosen by the stack (defaults to NSAPI_UNSPEC).
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t gethostbyname(const char *host,
                                         SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC);
 
-    /** Hostname translation callback (asynchronous)
+    /** Hostname translation callback (for use with gethostbyname_async()).
      *
      *  Callback will be called after DNS resolution completes or a failure occurs.
      *
-     *  Callback should not take more than 10ms to execute, otherwise it might
+     *  @note Callback should not take more than 10ms to execute, otherwise it might
      *  prevent underlying thread processing. A portable user of the callback
      *  should not make calls to network operations due to stack size limitations.
      *  The callback should not perform expensive operations such as socket recv/send
      *  calls or blocking operations.
      *
-     *  @param status  0 on success, negative error code on failure
-     *  @param address On success, destination for the host SocketAddress
+     *  @param result  NSAPI_ERROR_OK on success, negative error code on failure.
+     *  @param address On success, destination for the host SocketAddress.
      */
     typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t;
 
-    /** Translates a hostname to an IP address (asynchronous)
+    /** Translate a hostname to an IP address (asynchronous).
      *
-     *  The hostname may be either a domain name or an IP address. If the
+     *  The hostname may be either a domain name or a dotted IP address. If the
      *  hostname is an IP address, no network transactions will be performed.
      *
      *  If no stack-specific DNS resolution is provided, the hostname
@@ -192,87 +189,100 @@ class NetworkInterface: public DNS {
      *  is success (IP address was found from DNS cache), callback will be called
      *  before function returns.
      *
-     *  @param host     Hostname to resolve
-     *  @param callback Callback that is called for result
+     *  @param host     Hostname to resolve.
+     *  @param callback Callback that is called for result.
      *  @param version  IP version of address to resolve, NSAPI_UNSPEC indicates
-     *                  version is chosen by the stack (defaults to NSAPI_UNSPEC)
+     *                  version is chosen by the stack (defaults to NSAPI_UNSPEC).
      *  @return         0 on immediate success,
      *                  negative error code on immediate failure or
      *                  a positive unique id that represents the hostname translation operation
-     *                  and can be passed to cancel
+     *                  and can be passed to cancel.
      */
     virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback,
                                                        nsapi_version_t version = NSAPI_UNSPEC);
 
-    /** Cancels asynchronous hostname translation
+    /** Cancel asynchronous hostname translation.
      *
      *  When translation is cancelled, callback will not be called.
      *
-     *  @param id       Unique id of the hostname translation operation
-     *  @return         0 on success, negative error code on failure
+     *  @param id       Unique id of the hostname translation operation (returned
+     *                  by gethostbyname_async)
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t gethostbyname_async_cancel(int id);
 
     /** Add a domain name server to list of servers to query
      *
-     *  @param address  Destination for the host address
-     *  @return         0 on success, negative error code on failure
+     *  @param address  Address for the dns host.
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t add_dns_server(const SocketAddress &address);
 
-    /** Register callback for status reporting
+    /** Register callback for status reporting.
      *
      *  The specified status callback function will be called on status changes
      *  on the network. The parameters on the callback are the event type and
      *  event-type dependent reason parameter.
      *
-     *  @param status_cb The callback for status changes
+     *  @param status_cb The callback for status changes.
      */
     virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
 
-    /** Get the connection status
+    /** Get the connection status.
      *
-     *  @return         The connection status according to ConnectionStatusType
+     *  @return The connection status (@see nsapi_types.h).
      */
     virtual nsapi_connection_status_t get_connection_status() const;
 
-    /** Set blocking status of connect() which by default should be blocking
+    /** Set blocking status of connect() which by default should be blocking.
      *
-     *  @param blocking true if connect is blocking
-     *  @return         0 on success, negative error code on failure
+     *  @param blocking Use true to make connect() blocking.
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t set_blocking(bool blocking);
 
-    /** Dynamic downcast to an EthInterface */
+    /** Return pointer to an EthInterface.
+     * @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
+     */
     virtual EthInterface *ethInterface()
     {
         return 0;
     }
 
-    /** Dynamic downcast to a WiFiInterface */
+    /** Return pointer to a WiFiInterface.
+     * @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
+     */
     virtual WiFiInterface *wifiInterface()
     {
         return 0;
     }
 
-    /** Dynamic downcast to a MeshInterface */
+    /** Return pointer to a MeshInterface.
+     * @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
+     */
     virtual MeshInterface *meshInterface()
     {
         return 0;
     }
 
-    /** Dynamic downcast to a CellularBase */
+    /** Return pointer to a CellularBase.
+     * @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
+     */
     virtual CellularBase *cellularBase()
     {
         return 0;
     }
 
-    /** Dynamic downcast to an EMACInterface */
+    /** Return pointer to an EMACInterface.
+     * @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
+     */
     virtual EMACInterface *emacInterface()
     {
         return 0;
     }
 
+#if !defined(DOXYGEN_ONLY)
+
 protected:
     friend class InternetSocket;
     friend class UDPSocket;
@@ -318,6 +328,7 @@ class NetworkInterface: public DNS {
      * performs the search described by get_default_instance.
      */
     static NetworkInterface *get_target_default_instance();
+#endif //!defined(DOXYGEN_ONLY)
 };
 
 
diff --git a/features/netsocket/NetworkStack.h b/features/netsocket/NetworkStack.h
index 2ea7757dcab..8edb9e06453 100644
--- a/features/netsocket/NetworkStack.h
+++ b/features/netsocket/NetworkStack.h
@@ -54,10 +54,10 @@ class NetworkStack: public DNS {
      *  will be resolve using a UDP socket on the stack.
      *
      *  @param host     Hostname to resolve
-     *  @param address  Destination for the host SocketAddress
+     *  @param address  Pointer to a SocketAddress to store the result.
      *  @param version  IP version of address to resolve, NSAPI_UNSPEC indicates
      *                  version is chosen by the stack (defaults to NSAPI_UNSPEC)
-     *  @return         0 on success, negative error code on failure
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t gethostbyname(const char *host,
                                         SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC);
@@ -72,7 +72,7 @@ class NetworkStack: public DNS {
      *  The callback should not perform expensive operations such as socket recv/send
      *  calls or blocking operations.
      *
-     *  @param status  0 on success, negative error code on failure
+     *  @param status  NSAPI_ERROR_OK on success, negative error code on failure
      *  @param address On success, destination for the host SocketAddress
      */
     typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t;
@@ -107,14 +107,14 @@ class NetworkStack: public DNS {
      *  When translation is cancelled, callback will not be called.
      *
      *  @param id       Unique id of the hostname translation operation
-     *  @return         0 on success, negative error code on failure
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t gethostbyname_async_cancel(int id);
 
     /** Add a domain name server to list of servers to query
      *
      *  @param address  Destination for the host address
-     *  @return         0 on success, negative error code on failure
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t add_dns_server(const SocketAddress &address);
 
@@ -125,7 +125,7 @@ class NetworkStack: public DNS {
      *
      *  @param index    Index of the DNS server, starts from zero
      *  @param address  Destination for the host address
-     *  @return         0 on success, negative error code on failure
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t get_dns_server(int index, SocketAddress *address);
 
@@ -142,7 +142,7 @@ class NetworkStack: public DNS {
      *  @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
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t setstackopt(int level, int optname, const void *optval, unsigned optlen);
 
@@ -156,7 +156,7 @@ class NetworkStack: public DNS {
      *  @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
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t getstackopt(int level, int optname, void *optval, unsigned *optlen);
 
@@ -182,7 +182,7 @@ class NetworkStack: public DNS {
      *
      *  @param handle   Destination for the handle to a newly created socket
      *  @param proto    Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
-     *  @return         0 on success, negative error code on failure
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto) = 0;
 
@@ -192,7 +192,7 @@ class NetworkStack: public DNS {
      *  with the socket.
      *
      *  @param handle   Socket handle
-     *  @return         0 on success, negative error code on failure
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t socket_close(nsapi_socket_t handle) = 0;
 
@@ -203,7 +203,7 @@ class NetworkStack: public DNS {
      *
      *  @param handle   Socket handle
      *  @param address  Local address to bind
-     *  @return         0 on success, negative error code on failure.
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address) = 0;
 
@@ -215,7 +215,7 @@ class NetworkStack: public DNS {
      *  @param handle   Socket handle
      *  @param backlog  Number of pending connections that can be queued
      *                  simultaneously
-     *  @return         0 on success, negative error code on failure
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog) = 0;
 
@@ -226,7 +226,7 @@ class NetworkStack: public DNS {
      *
      *  @param handle   Socket handle
      *  @param address  The SocketAddress of the remote host
-     *  @return         0 on success, negative error code on failure
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address) = 0;
 
@@ -246,7 +246,7 @@ class NetworkStack: public DNS {
      *  @param server   Socket handle to server to accept from
      *  @param handle   Destination for a handle to the newly created socket
      *  @param address  Destination for the remote address or NULL
-     *  @return         0 on success, negative error code on failure
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t socket_accept(nsapi_socket_t server,
                                         nsapi_socket_t *handle, SocketAddress *address = 0) = 0;
@@ -336,34 +336,34 @@ class NetworkStack: public DNS {
      */
     virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), void *data) = 0;
 
-    /*  Set stack-specific socket options
+    /**  Set stack-specific socket options.
      *
      *  The setsockopt allow an application to pass stack-specific hints
      *  to the underlying stack. For unsupported options,
      *  NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
      *
-     *  @param handle   Socket handle
-     *  @param level    Stack-specific protocol level
-     *  @param optname  Stack-specific option identifier
-     *  @param optval   Option value
-     *  @param optlen   Length of the option value
-     *  @return         0 on success, negative error code on failure
+     *  @param handle   Socket handle.
+     *  @param level    Stack-specific protocol level.
+     *  @param optname  Stack-specific option identifier.
+     *  @param optval   Option value.
+     *  @param optlen   Length of the option value.
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
                                      int optname, const void *optval, unsigned optlen);
 
-    /*  Get stack-specific socket options
+    /**  Get stack-specific socket options.
      *
      *  The getstackopt allow an application to retrieve stack-specific hints
      *  from the underlying stack. For unsupported options,
      *  NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
      *
-     *  @param handle   Socket handle
-     *  @param level    Stack-specific protocol level
-     *  @param optname  Stack-specific option identifier
-     *  @param optval   Destination for option value
-     *  @param optlen   Length of the option value
-     *  @return         0 on success, negative error code on failure
+     *  @param handle   Socket handle.
+     *  @param level    Stack-specific protocol level.
+     *  @param optname  Stack-specific option identifier.
+     *  @param optval   Destination for option value.
+     *  @param optlen   Length of the option value.
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level,
                                      int optname, void *optval, unsigned *optlen);
@@ -397,7 +397,7 @@ class NetworkStack: public DNS {
      *
      *  @param delay    Delay in milliseconds
      *  @param func     Callback to be called
-     *  @return         0 on success, negative error code on failure
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t call_in(int delay, mbed::Callback<void()> func);
 };
diff --git a/features/netsocket/Socket.h b/features/netsocket/Socket.h
index fe560b4be7b..cc6b8f51524 100644
--- a/features/netsocket/Socket.h
+++ b/features/netsocket/Socket.h
@@ -38,7 +38,7 @@ class Socket {
      *  Closes any open connection and deallocates any memory associated
      *  with the socket. Called from destructor if socket is not closed.
      *
-     *  @return         0 on success, negative error code on failure
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t close() = 0;
 
@@ -54,7 +54,7 @@ class Socket {
      *  object have to be in the address parameter.
      *
      *  @param address  The SocketAddress of the remote peer
-     *  @return         0 on success, negative error code on failure
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t connect(const SocketAddress &address) = 0;
 
@@ -142,10 +142,11 @@ class Socket {
 
     /** Bind a specific address to a socket.
      *
-     *  Binding assigns a local 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.
      *
      *  @param address  Local address to bind
-     *  @return         0 on success, negative error code on failure.
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t bind(const SocketAddress &address) = 0;
 
@@ -190,11 +191,11 @@ class Socket {
      *  such functionality. The exact timing of when the registered function
      *  is called is not guaranteed and 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) = 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,
@@ -203,15 +204,15 @@ class Socket {
      *  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         NSAPI_ERROR_OK on success, negative error code on failure.
      */
     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,
@@ -220,11 +221,11 @@ class Socket {
      *  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         NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) = 0;
 
@@ -250,7 +251,7 @@ class Socket {
      *
      *  @param backlog  Number of pending connections that can be queued
      *                  simultaneously, defaults to 1
-     *  @return         0 on success, negative error code on failure
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure
      */
     virtual nsapi_error_t listen(int backlog = 1) = 0;
 };
diff --git a/features/netsocket/WiFiInterface.h b/features/netsocket/WiFiInterface.h
index 1b876d7e65a..e0d65abecf4 100644
--- a/features/netsocket/WiFiInterface.h
+++ b/features/netsocket/WiFiInterface.h
@@ -22,104 +22,103 @@
 #include "netsocket/NetworkInterface.h"
 #include "netsocket/WiFiAccessPoint.h"
 
-/** WiFiInterface class
+/** Common interface that is shared between Wi-Fi devices.
  *
- *  Common interface that is shared between WiFi devices
  *  @addtogroup netsocket
  */
 class WiFiInterface: public virtual NetworkInterface {
 public:
-    /** Get the default WiFi interface.
+    /** Get the default Wi-Fi interface.
      *
      * This is provided as a weak method so applications can override.
      * Default behaviour is to get the target's default interface, if
      * any.
      *
-     * @return pointer to interface, if any
+     * @return pointer to interface, if any.
      */
     static WiFiInterface *get_default_instance();
 
-    /** Set the WiFi network credentials
+    /** Set the Wi-Fi network credentials.
      *
-     *  @param ssid      Name of the network to connect to
-     *  @param pass      Security passphrase to connect to the network
+     *  @param ssid      Name of the network to connect to.
+     *  @param pass      Security passphrase to connect to the network.
      *  @param security  Type of encryption for connection
-     *                   (defaults to NSAPI_SECURITY_NONE)
-     *  @return          0 on success, or error code on failure
+     *                   (defaults to NSAPI_SECURITY_NONE).
+     *  @return          NSAPI_ERROR_OK on success, or error code on failure.
      */
     virtual nsapi_error_t set_credentials(const char *ssid, const char *pass,
                                           nsapi_security_t security = NSAPI_SECURITY_NONE) = 0;
 
-    /** Set the WiFi network channel
+    /** Set the Wi-Fi network channel.
      *
-     *  @param channel   Channel on which the connection is to be made, or 0 for any (Default: 0)
-     *  @return          0 on success, or error code on failure
+     *  @param channel   Channel on which the connection is to be made, or 0 for any (Default: 0).
+     *  @return          NSAPI_ERROR_OK on success, or error code on failure.
      */
     virtual nsapi_error_t set_channel(uint8_t channel) = 0;
 
-    /** Gets the current radio signal strength for active connection
+    /** Get the current radio signal strength for active connection.
      *
      *  @return         Connection strength in dBm (negative value),
-     *                  or 0 if measurement impossible
+     *                  or 0 if measurement impossible.
      */
     virtual int8_t get_rssi() = 0;
 
-    /** Start the interface
+    /** Attempt to connect to a Wi-Fi network.
      *
-     *  Attempts to connect to a WiFi network.
-     *
-     *  @param ssid      Name of the network to connect to
-     *  @param pass      Security passphrase to connect to the network
-     *  @param security  Type of encryption for connection (Default: NSAPI_SECURITY_NONE)
-     *  @param channel   Channel on which the connection is to be made, or 0 for any (Default: 0)
-     *  @return          0 on success, or error code on failure
+     *  @param ssid      Name of the network to connect to.
+     *  @param pass      Security passphrase to connect to the network.
+     *  @param security  Type of encryption for connection (Default: NSAPI_SECURITY_NONE).
+     *  @param channel   Channel on which the connection is to be made, or 0 for any (Default: 0).
+     *  @return          NSAPI_ERROR_OK on success, or error code on failure.
      */
     virtual nsapi_error_t connect(const char *ssid, const char *pass,
                                   nsapi_security_t security = NSAPI_SECURITY_NONE, uint8_t channel = 0) = 0;
 
-    /** Start the interface
-     *
-     *  Attempts to connect to a WiFi network. Requires ssid and passphrase to be set.
+    /** Attempt to connect to a Wi-Fi network. Requires ssid and passphrase to be set.
      *  If passphrase is invalid, NSAPI_ERROR_AUTH_ERROR is returned.
      *
-     *  @return         0 on success, negative error code on failure
+     *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
      */
     virtual nsapi_error_t connect() = 0;
 
-    /** Stop the interface
+    /** Stop the interface.
      *
-     *  @return         0 on success, or error code on failure
+     *  @return         NSAPI_ERROR_OK on success, or error code on failure.
      */
     virtual nsapi_error_t disconnect() = 0;
 
-    /** Scan for available networks
+    /** Scan for available networks.
      *
-     *  This function will block. If the @a count is 0, function will only return count of available networks, so that
-     *  user can allocated necessary memory. If the \p count is grater than 0 and the a \p res is not NULL it'll be populated
-     *  with discovered networks up to value of \p count.
+     *  This function will block. If the count is 0, function will only return count of available networks, so that
+     *  user can allocated necessary memory. If the count is grater than 0 and the a \p res is not NULL it'll be populated
+     *  with discovered networks up to value of count.
      *
-     *  @param  res      Pointer to allocated array to store discovered AP
-     *  @param  count    Size of allocated @a res array, or 0 to only count available AP
-     *  @return          Number of entries in \p count, or if \p count was 0 number of available networks,
-     *                   negative on error see @a nsapi_error
+     *  @param  res      Pointer to allocated array to store discovered APs.
+     *  @param  count    Size of allocated res array, or 0 to only count available APs.
+     *  @return          Number of entries in res, or if count was 0 number of available networks.
+     *                   Negative on error (@see nsapi_types.h for nsapi_error).
      */
     virtual nsapi_size_or_error_t scan(WiFiAccessPoint *res, nsapi_size_t count) = 0;
 
+    /** @copydoc NetworkInterface::wifiInterface
+     */
     virtual WiFiInterface *wifiInterface()
     {
         return this;
     }
 
+#if !defined(DOXYGEN_ONLY)
 protected:
 
-    /** Get the target's default WiFi interface.
+    /** Get the target's default Wi-Fi interface.
      *
      * This is provided as a weak method so targets can override. The
      * default implementation returns NULL.
      *
-     * @return pointer to interface, if any
+     * @return pointer to interface, if any.
      */
     static WiFiInterface *get_target_default_instance();
+#endif //!defined(DOXYGEN_ONLY)
 };
 
 #endif
diff --git a/features/netsocket/nsapi_types.h b/features/netsocket/nsapi_types.h
index 232236b6c66..7f701d0de56 100644
--- a/features/netsocket/nsapi_types.h
+++ b/features/netsocket/nsapi_types.h
@@ -351,7 +351,7 @@ typedef struct nsapi_stack_api {
      */
     nsapi_error_t (*add_dns_server)(nsapi_stack_t *stack, nsapi_addr_t addr);
 
-    /*  Set stack-specific stack options
+    /** Set stack-specific stack options
      *
      *  The setstackopt allow an application to pass stack-specific hints
      *  to the underlying stack. For unsupported options,
@@ -367,7 +367,7 @@ typedef struct nsapi_stack_api {
     nsapi_error_t (*setstackopt)(nsapi_stack_t *stack, int level,
                                  int optname, const void *optval, unsigned optlen);
 
-    /*  Get stack-specific stack options
+    /** Get stack-specific stack options
      *
      *  The getstackopt allow an application to retrieve stack-specific hints
      *  from the underlying stack. For unsupported options,
@@ -567,7 +567,7 @@ typedef struct nsapi_stack_api {
     void (*socket_attach)(nsapi_stack_t *stack, nsapi_socket_t socket,
                           void (*callback)(void *), void *data);
 
-    /*  Set stack-specific socket options
+    /** Set stack-specific socket options
      *
      *  The setsockopt allow an application to pass stack-specific hints
      *  to the underlying stack. For unsupported options,
@@ -584,7 +584,7 @@ typedef struct nsapi_stack_api {
     nsapi_error_t (*setsockopt)(nsapi_stack_t *stack, nsapi_socket_t socket, int level,
                                 int optname, const void *optval, unsigned optlen);
 
-    /*  Get stack-specific socket options
+    /** Get stack-specific socket options
      *
      *  The getstackopt allow an application to retrieve stack-specific hints
      *  from the underlying stack. For unsupported options,