Merge pull request #6652 from jarvte/update_doxygen_for_deprecated_apis

0xc0170 · web-flow · commit 7f98f5b79690 · 2018-04-19T17:23:53.000+02:00
Cellular: Updated doxygen for deprecated API's.
diff --git a/features/netsocket/CellularInterface.h b/features/netsocket/CellularInterface.h
@@ -20,6 +20,8 @@
 #include "netsocket/NetworkInterface.h"
 
 /** CellularInterface class
+ *
+ *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/framework/API/CellularNetwork.h instead.
  *
  *  Common interface that is shared between ethernet hardware
  *  @addtogroup netsocket
@@ -33,6 +35,8 @@ class CellularInterface : public NetworkInterface
     virtual ~CellularInterface() {};
 
     /** Set the cellular network APN and credentials
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/framework/API/CellularNetwork.h instead.
      *
      *  @param apn      Optional name of the network to connect to
      *  @param username Optional username for the APN
@@ -44,6 +48,8 @@ class CellularInterface : public NetworkInterface
             const char *username = 0, const char *password = 0) = 0;
 
     /** Start the interface
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/framework/API/CellularNetwork.h instead.
      *
      *  @param apn      Optional name of the network to connect to
      *  @param username Optional username for your APN
@@ -55,6 +61,8 @@ class CellularInterface : public NetworkInterface
             const char *username = 0, const char *password = 0) = 0;
 
     /** Start the interface
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/framework/API/CellularNetwork.h instead.
      *
      *  Attempts to connect to a cellular network based on supplied credentials
      *
@@ -64,6 +72,8 @@ class CellularInterface : public NetworkInterface
     virtual nsapi_error_t connect() = 0;
 
     /** Stop the interface
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/framework/API/CellularNetwork.h instead.
      *
      *  @return         0 on success, negative error code on failure
      */
diff --git a/features/netsocket/cellular/generic_modem_driver/OnboardCellularInterface.h b/features/netsocket/cellular/generic_modem_driver/OnboardCellularInterface.h
@@ -24,6 +24,8 @@ typedef mbed::EasyCellularConnection OnboardCellularInterface;
 #include "UARTCellularInterface.h"
 
 /** OnboardCellularInterface class
+ *
+ *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/framework/API/CellularPower.h instead.
  *
  *  This interface serves as the controller/driver for an
  *  onboard modem implementing onboard_modem_api.h.
@@ -37,14 +39,22 @@ class OnboardCellularInterface : public UARTCellularInterface {
 
 public:
 
+    /** Constructor
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/framework/API/CellularPower.h instead.
+     */
     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/framework/API/CellularPower.h instead.")
     OnboardCellularInterface(bool debug = false);
 
+    /** Destructor
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/framework/API/CellularPower.h instead.
+     */
     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/framework/API/CellularPower.h instead.")
     virtual ~OnboardCellularInterface();
 
 protected:
     /** Sets the modem up for powering on
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/framework/API/CellularPower.h instead.
      *
      *  modem_init() is equivalent to plugging in the device, for example, attaching power and serial port.
      *  Uses onboard_modem_api.h where the target provides the implementation of onboard_modem_api.
@@ -53,6 +63,8 @@ class OnboardCellularInterface : public UARTCellularInterface {
     virtual void modem_init();
 
     /** Sets the modem in unplugged state
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/framework/API/CellularPower.h instead.
      *
      *  modem_deinit() will be equivalent to pulling the plug off of the device, in other words, detaching power
      *  and serial port. This puts the modem in lowest power state.
@@ -62,6 +74,8 @@ class OnboardCellularInterface : public UARTCellularInterface {
     virtual void modem_deinit();
 
     /** Powers up the modem
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/framework/API/CellularPower.h instead.
      *
      *  modem_power_up() is equivalent to pressing the soft power button.
      *  The driver may repeat this if the modem is not responsive to AT commands.
@@ -71,6 +85,8 @@ class OnboardCellularInterface : public UARTCellularInterface {
     virtual void modem_power_up();
 
     /** Powers down the modem
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/framework/API/CellularPower.h instead.
      *
      *  modem_power_down() is equivalent to turning off the modem by button press.
      *  Uses onboard_modem_api.h where the target provides the implementation of onboard_modem_api.
diff --git a/features/netsocket/cellular/generic_modem_driver/PPPCellularInterface.h b/features/netsocket/cellular/generic_modem_driver/PPPCellularInterface.h
@@ -91,6 +91,8 @@ typedef struct {
 } device_info;
 
 /** PPPCellularInterface class
+ *
+ *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
  *
  *  This interface serves as the controller/driver for the Cellular
  *  modems (tested with UBLOX_C027 and MTS_DRAGONFLY_F411RE).
@@ -105,17 +107,25 @@ class PPPCellularInterface : public CellularBase {
 public:
 
     /** Constructor for a generic modem, using a single FileHandle for commands and PPP data.
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
      *
      * The file handle pointer is not accessed within the constructor, only recorded for later
      * use - this permits a derived class to pass a pointer to a not-yet-constructed member object.
      */
     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
     PPPCellularInterface(FileHandle *fh, bool debug = false);
 
+    /** Destructor
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
+     */
     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
     virtual ~PPPCellularInterface();
 
     /** Set the Cellular network credentials
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
      *
      *  Please check documentation of connect() for default behaviour of APN settings.
      *
@@ -128,13 +138,17 @@ class PPPCellularInterface : public CellularBase {
                                                   const char *pwd = 0);
 
     /** Set the pin code for SIM card
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
      *
      *  @param sim_pin      PIN for the SIM card
      */
     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
     virtual void set_sim_pin(const char *sim_pin);
 
     /** Start the interface
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
      *
      *  Attempts to connect to a Cellular network.
      *  This driver is written mainly for data network connections as CellularInterface
@@ -154,6 +168,8 @@ class PPPCellularInterface : public CellularBase {
                                   const char *uname = 0, const char *pwd = 0);
 
     /** Attempt to connect to the Cellular network
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
      *
      *  Brings up the network interface. Connects to the Cellular Radio
      *  network and then brings up the underlying network stack to be used
@@ -187,6 +203,8 @@ class PPPCellularInterface : public CellularBase {
     virtual nsapi_error_t disconnect();
 
     /** Adds or removes a SIM facility lock
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
      *
      * Can be used to enable or disable SIM pin check at device startup.
      * This API sets up flags for the driver which would either enable or disable
@@ -200,6 +218,8 @@ class PPPCellularInterface : public CellularBase {
     void set_sim_pin_check(bool set);
 
     /** Change the pin for the SIM card
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
      *
      * Provide the new pin for your SIM card with this API. Old pin code will be assumed to
      * be set using set_SIM_pin() API. This API have no immediate effect. While establishing
@@ -211,6 +231,8 @@ class PPPCellularInterface : public CellularBase {
     void set_new_sim_pin(const char *new_pin);
 
     /** Check if the connection is currently established or not
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
      *
      * @return true/false   If the cellular module have successfully acquired a carrier and is
      *                      connected to an external packet data network using PPP, isConnected()
@@ -220,6 +242,8 @@ class PPPCellularInterface : public CellularBase {
     virtual bool is_connected();
 
     /** Get the local IP address
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
      *
      *  @return         Null-terminated representation of the local IP address
      *                  or null if no IP address has been received
@@ -228,6 +252,8 @@ class PPPCellularInterface : public CellularBase {
     virtual const char *get_ip_address();
 
     /** Get the local network mask
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
      *
      *  @return         Null-terminated representation of the local network mask
      *                  or null if no network mask has been received
@@ -236,6 +262,8 @@ class PPPCellularInterface : public CellularBase {
     virtual const char *get_netmask();
 
     /** Get the local gateways
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
      *
      *  @return         Null-terminated representation of the local gateway
      *                  or null if no network mask has been received
@@ -252,20 +280,26 @@ class PPPCellularInterface : public CellularBase {
     void modem_debug_on(bool on);
 
     /** Register callback for status reporting
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
      *
      *  @param status_cb The callback for status changes
      */
     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
     virtual void attach(Callback<void(nsapi_event_t, intptr_t)> status_cb);
 
     /** Get the connection status
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
      *
      *  @return         The connection status according to nsapi_connection_status_t
      */
     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
     virtual nsapi_connection_status_t get_connection_status() const;
 
     /** Set blocking status of connect() which by default should be blocking
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
      *
      *  @param blocking true if connect is blocking
      *  @return         0 on success, negative error code on failure
diff --git a/features/netsocket/cellular/generic_modem_driver/UARTCellularInterface.h b/features/netsocket/cellular/generic_modem_driver/UARTCellularInterface.h
@@ -22,6 +22,8 @@
 #if NSAPI_PPP_AVAILABLE
 
 /** UARTCellularInterface class
+ *
+ *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
  *
  *  This interface serves as the controller/driver for Cellular
  *  modems attached via a UART (tested with UBLOX_C027 and MTS_DRAGONFLY_F411RE).
@@ -34,12 +36,20 @@ class UARTCellularInterface : public PPPCellularInterface {
 
 public:
 
+    /** Constructor
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
+     */
     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
     UARTCellularInterface(PinName tx, PinName rx, PinName dcd = NC, PinName rts = NC, PinName cts = NC, PinName ri = NC,
                              PinName dtr = NC, PinName dsr = NC, int baud = MBED_CONF_PPP_CELL_IFACE_BAUD_RATE,
                              bool active_high = false,
                              bool debug = false);
 
+    /** Destructor
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
+     */
     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
     virtual ~UARTCellularInterface();
 
@@ -50,6 +60,8 @@ class UARTCellularInterface : public PPPCellularInterface {
 
 protected:
     /** Enable or disable hang-up detection
+     *
+     *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
      *
      *  When in PPP data pump mode, it is helpful if the FileHandle will signal hang-up via
      *  POLLHUP, e.g., if the DCD line is deasserted on a UART. During command mode, this
