Merge pull request #12121 from hugueskamba/hk-deprecate-serial-class

Serial: Deprecate the class and promote UnbufferedSerial instead

Author: adbridge

drivers/Serial.h

@@ -33,7 +33,8 @@ namespace mbed {
  * @{
  */
 
-/** A serial port (UART) for communication with other serial devices
+/** @deprecated
+ * A serial port (UART) for communication with other serial devices
  *
  * Can be used for Full Duplex communication, or Simplex by specifying
  * one pin as NC (Not Connected)
@@ -53,7 +54,11 @@ namespace mbed {
  * }
  * @endcode
  */
-class Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
+class
+    MBED_DEPRECATED_SINCE(
+        "mbed-os-6.0.0",
+        "Use printf and puts instead to access the console, BufferedSerial for blocking applications or UnbufferedSerial if bypassing locks in IRQ or short of RAM."
+    ) Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
 
 public:
 #if DEVICE_SERIAL_ASYNCH
@@ -67,7 +72,8 @@ class Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
     using SerialBase::enable_input;
     using SerialBase::enable_output;
 
-    /** Create a Serial port, connected to the specified transmit and receive pins
+    /** @deprecated
+     * Create a Serial port, connected to the specified transmit and receive pins
      *
      *  @param tx Transmit pin
      *  @param rx Receive pin
@@ -77,9 +83,11 @@ class Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
      *  @note
      *    Either tx or rx may be specified as NC (Not Connected) if unused
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     Serial(PinName tx, PinName rx, const char *name = NULL, int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE);
 
-    /** Create a Serial port, connected to the specified transmit and receive pins
+    /** @deprecated
+     * Create a Serial port, connected to the specified transmit and receive pins
      *
      *  @param static_pinmap reference to structure which holds static pinmap.
      *  @param name The name of the stream associated with this serial port (optional)
@@ -88,10 +96,13 @@ class Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
      *  @note
      *    Either tx or rx may be specified as NC (Not Connected) if unused
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     Serial(const serial_pinmap_t &static_pinmap, const char *name = NULL, int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE);
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     Serial(const serial_pinmap_t &&, const char * = NULL, int = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE) = delete; // prevent passing of temporary objects
 
-    /** Create a Serial port, connected to the specified transmit and receive pins, with the specified baud
+    /** @deprecated
+     * Create a Serial port, connected to the specified transmit and receive pins, with the specified baud
      *
      *  @param tx Transmit pin
      *  @param rx Receive pin
@@ -100,31 +111,38 @@ class Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
      *  @note
      *    Either tx or rx may be specified as NC (Not Connected) if unused
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     Serial(PinName tx, PinName rx, int baud);
 
-    /** Create a Serial port, connected to the specified transmit and receive pins, with the specified baud
+    /** @deprecated
+     * Create a Serial port, connected to the specified transmit and receive pins, with the specified baud
      *
      *  @param static_pinmap reference to structure which holds static pinmap.
      *  @param baud The baud rate of the serial port
      *
      *  @note
      *    Either tx or rx may be specified as NC (Not Connected) if unused
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     Serial(const serial_pinmap_t &static_pinmap, int baud);
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     Serial(const serial_pinmap_t &&, int) = delete; // prevent passing of temporary objects
 
     /* Stream gives us a FileHandle with non-functional poll()/readable()/writable. Pass through
      * the calls from the SerialBase instead for backwards compatibility. This problem is
      * part of why Stream and Serial should be deprecated.
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     bool readable()
     {
         return SerialBase::readable();
     }
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     bool writable()
     {
         return SerialBase::writeable();
     }
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     bool writeable()
     {
         return SerialBase::writeable();