Merge branch 'docs-fix-networkiface' of ssh://github.com/paul-szczepanek-arm/mbed-os into rollup

Author: Cruz Monrreal II

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);

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

features/netsocket/DNS.h

@@ -20,76 +20,76 @@
 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.
      *
      *  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
      *  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
      *  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;
 };

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)
 };
 
 

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) { }