doxygen fixes

Author: paul-szczepanek-arm

features/netsocket/CellularBase.h

@@ -18,105 +18,102 @@
 
 #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.
      *
      * 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
+    /** Attempt to connect to a Cellular network with a pin and credentials.
      *
-     *  Attempts to connect to a Cellular network.
-     *
-     *  @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 is 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 or not.
      *
-     * @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
+     *                  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
+     *                  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
+     *                  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.
      *
@@ -127,6 +124,8 @@ class CellularBase: public NetworkInterface {
      * @return pointer to interface, if any
      */
     static CellularBase *get_target_default_instance();
+
+#endif //!defined(DOXYGEN_ONLY)
 };
 
 #endif //CELLULAR_BASE_H

features/netsocket/EthInterface.h

@@ -23,13 +23,14 @@
 #include "netsocket/NetworkInterface.h"
 
 
-/** EthInterface class
- *
- *  Common interface that is shared between ethernet hardware.
+/** Common interface that is shared between Ethernet hardware.
+ *  @addtogroup netsocket
  */
 class EthInterface : public virtual NetworkInterface {
 public:
 
+    /** @copydoc NetworkInterface::ethInterface
+     */
     virtual EthInterface *ethInterface()
     {
         return this;
@@ -41,10 +42,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 +55,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) { }

features/netsocket/MeshInterface.h

@@ -23,13 +23,13 @@
 #include "netsocket/NetworkInterface.h"
 
 
-/** MeshInterface class
- *
- *  Common interface that is shared between mesh hardware
+/** Common interface that is shared between mesh hardware
+ *  @addtogroup netsocket
  */
 class MeshInterface : public virtual NetworkInterface {
 public:
-
+    /** @copydoc NetworkInterface::meshInterface
+     */
     virtual MeshInterface *meshInterface()
     {
         return this;
@@ -41,10 +41,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 +54,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)
 };