Mark some dependencies as unstable (#2668)

* Mark some dependencies as unstable * Fix docs * Pass unstable to doctests * Document the unstable feature
esp-rs · Dec 4, 2024 · 91d7f23 · 91d7f23
1 parent a189eff
commit 91d7f23
Show file tree

Hide file tree

Showing 10 changed files with 147 additions and 26 deletions.
diff --git a/esp-hal/Cargo.toml b/esp-hal/Cargo.toml
@@ -25,17 +25,17 @@ defmt                    = { version = "0.3.8", optional = true }
 delegate                 = "0.13.1"
 digest                   = { version = "0.10.7", default-features = false, optional = true }
 document-features        = "0.2.10"
-embassy-embedded-hal     = "0.2.0"
+embassy-embedded-hal     = { version = "0.2.0", optional = true }
 embassy-futures          = "0.1.1"
 embassy-sync             = "0.6.1"
 embassy-usb-driver       = { version = "0.1.0", optional = true }
 embassy-usb-synopsys-otg = { version = "0.1.0", optional = true }
-embedded-can             = "0.4.1"
+embedded-can             = { version = "0.4.1", optional = true }
 embedded-hal             = "1.0.0"
 embedded-hal-async       = "1.0.0"
 embedded-hal-nb          = "1.0.0"
-embedded-io              = "0.6.1"
-embedded-io-async        = "0.6.1"
+embedded-io              = { version = "0.6.1", optional = true }
+embedded-io-async        = { version = "0.6.1", optional = true }
 enumset                  = "1.1.5"
 esp-build                = { version = "0.1.0", path = "../esp-build" }
 esp-synopsys-usb-otg     = { version = "0.4.2", optional = true, features = ["fs", "esp32sx"] }
@@ -153,8 +153,18 @@ octal-psram = []
 # This feature is intended for testing; you probably don't want to enable it:
 ci = ["defmt", "bluetooth"]
 
-# Enables APIs that are not stable and thus come with no stability guarantees.
-unstable = []
+#! ### Unstable APIs
+#! Unstable APIs are drivers and features that are not yet ready for general use.
+#! They may be incomplete, have bugs, or be subject to change without notice.
+#! Unstable APIs are not covered by semver guarantees.
+
+## Enables APIs that are not stable and thus come with no stability guarantees.
+unstable = [
+    "dep:embassy-embedded-hal",
+    "dep:embedded-can",
+    "dep:embedded-io",
+    "dep:embedded-io-async",
+]
 
 [lints.clippy]
 mixed_attributes_style = "allow"

diff --git a/esp-hal/src/i2c/master/mod.rs b/esp-hal/src/i2c/master/mod.rs
@@ -44,6 +44,7 @@ use core::{
     task::{Context, Poll},
 };
 
+#[cfg(any(doc, feature = "unstable"))]
 use embassy_embedded_hal::SetConfig;
 use embedded_hal::i2c::Operation as EhalOperation;
 use fugit::HertzU32;
@@ -280,6 +281,8 @@ pub struct I2c<'d, DM: Mode, T = AnyI2c> {
     guard: PeripheralGuard,
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<T: Instance, DM: Mode> SetConfig for I2c<'_, DM, T> {
     type Config = Config;
     type ConfigError = ConfigError;

diff --git a/esp-hal/src/spi/master.rs b/esp-hal/src/spi/master.rs
@@ -61,6 +61,7 @@
 use core::marker::PhantomData;
 
 pub use dma::*;
+#[cfg(any(doc, feature = "unstable"))]
 use embassy_embedded_hal::SetConfig;
 #[cfg(gdma)]
 use enumset::EnumSet;
@@ -648,6 +649,8 @@ where
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<M, T> SetConfig for Spi<'_, M, T>
 where
     T: Instance,
@@ -1168,6 +1171,8 @@ mod dma {
         }
     }
 
+    #[cfg(any(doc, feature = "unstable"))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
     impl<M, T> SetConfig for SpiDma<'_, M, T>
     where
         T: Instance,
@@ -1797,6 +1802,8 @@ mod dma {
         }
     }
 
+    #[cfg(any(doc, feature = "unstable"))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
     impl<M, T> SetConfig for SpiDmaBus<'_, M, T>
     where
         T: Instance,

diff --git a/esp-hal/src/twai/mod.rs b/esp-hal/src/twai/mod.rs
@@ -25,14 +25,12 @@
 //!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
-//! # use embedded_can::Id;
 //! # use esp_hal::twai;
 //! # use esp_hal::twai::filter;
 //! # use esp_hal::twai::filter::SingleStandardFilter;
 //! # use esp_hal::twai::TwaiConfiguration;
 //! # use esp_hal::twai::BaudRate;
 //! # use esp_hal::twai::TwaiMode;
-//! # use embedded_can::Frame;
 //! # use nb::block;
 //! // Use GPIO pins 2 and 3 to connect to the respective pins on the TWAI
 //! // transceiver.
@@ -75,7 +73,6 @@
 //! ### Self-testing (self reception of transmitted messages)
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
-//! # use embedded_can::Id;
 //! # use esp_hal::twai;
 //! # use esp_hal::twai::filter;
 //! # use esp_hal::twai::filter::SingleStandardFilter;
@@ -84,7 +81,6 @@
 //! # use esp_hal::twai::EspTwaiFrame;
 //! # use esp_hal::twai::StandardId;
 //! # use esp_hal::twai::TwaiMode;
-//! # use embedded_can::Frame;
 //! # use nb::block;
 //! // Use GPIO pins 2 and 3 to connect to the respective pins on the TWAI
 //! // transceiver.
@@ -205,6 +201,8 @@ impl_display! {
     Other => "A different error occurred. The original error may contain more information",
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl From<ErrorKind> for embedded_can::ErrorKind {
     fn from(value: ErrorKind) -> Self {
         match value {
@@ -219,6 +217,8 @@ impl From<ErrorKind> for embedded_can::ErrorKind {
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl embedded_can::Error for ErrorKind {
     fn kind(&self) -> embedded_can::ErrorKind {
         (*self).into()
@@ -280,12 +280,16 @@ impl StandardId {
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl From<StandardId> for embedded_can::StandardId {
     fn from(value: StandardId) -> Self {
         embedded_can::StandardId::new(value.as_raw()).unwrap()
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl From<embedded_can::StandardId> for StandardId {
     fn from(value: embedded_can::StandardId) -> Self {
         StandardId::new(value.as_raw()).unwrap()
@@ -340,12 +344,16 @@ impl ExtendedId {
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl From<ExtendedId> for embedded_can::ExtendedId {
     fn from(value: ExtendedId) -> Self {
         embedded_can::ExtendedId::new(value.0).unwrap()
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl From<embedded_can::ExtendedId> for ExtendedId {
     fn from(value: embedded_can::ExtendedId) -> Self {
         ExtendedId::new(value.as_raw()).unwrap()
@@ -376,6 +384,8 @@ impl From<ExtendedId> for Id {
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl From<Id> for embedded_can::Id {
     fn from(value: Id) -> Self {
         match value {
@@ -385,6 +395,8 @@ impl From<Id> for embedded_can::Id {
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl From<embedded_can::Id> for Id {
     fn from(value: embedded_can::Id) -> Self {
         match value {
@@ -394,7 +406,7 @@ impl From<embedded_can::Id> for Id {
     }
 }
 
-/// Structure backing the `embedded_can::Frame` trait.
+/// A TWAI Frame.
 #[derive(Clone, Copy, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct EspTwaiFrame {
@@ -486,6 +498,8 @@ impl EspTwaiFrame {
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl embedded_can::Frame for EspTwaiFrame {
     fn new(id: impl Into<embedded_can::Id>, data: &[u8]) -> Option<Self> {
         Self::new(id.into(), data)
@@ -1276,6 +1290,8 @@ pub enum EspTwaiError {
     EmbeddedHAL(ErrorKind),
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl embedded_can::Error for EspTwaiError {
     fn kind(&self) -> embedded_can::ErrorKind {
         if let Self::EmbeddedHAL(kind) = self {
@@ -1318,6 +1334,7 @@ unsafe fn copy_to_data_register(dest: *mut u32, src: &[u8]) {
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
 impl<DM, T> embedded_can::nb::Can for Twai<'_, DM, T>
 where
     T: Instance,

diff --git a/esp-hal/src/uart.rs b/esp-hal/src/uart.rs
@@ -226,6 +226,7 @@
 
 use core::{marker::PhantomData, sync::atomic::Ordering, task::Poll};
 
+#[cfg(any(doc, feature = "unstable"))]
 use embassy_embedded_hal::SetConfig;
 use enumset::{EnumSet, EnumSetType};
 use portable_atomic::AtomicBool;
@@ -292,6 +293,8 @@ impl embedded_hal_nb::serial::Error for Error {
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl embedded_io::Error for Error {
     fn kind(&self) -> embedded_io::ErrorKind {
         embedded_io::ErrorKind::Other
@@ -622,6 +625,8 @@ pub enum ConfigError {
     UnsupportedFifoThreshold,
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<M, T> SetConfig for Uart<'_, M, T>
 where
     T: Instance,
@@ -635,6 +640,8 @@ where
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<M, T> SetConfig for UartRx<'_, M, T>
 where
     T: Instance,
@@ -648,6 +655,8 @@ where
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<M, T> SetConfig for UartTx<'_, M, T>
 where
     T: Instance,
@@ -1460,18 +1469,26 @@ where
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<T, M> embedded_io::ErrorType for Uart<'_, M, T> {
     type Error = Error;
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<T, M> embedded_io::ErrorType for UartTx<'_, M, T> {
     type Error = Error;
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<T, M> embedded_io::ErrorType for UartRx<'_, M, T> {
     type Error = Error;
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<T, M> embedded_io::Read for Uart<'_, M, T>
 where
     T: Instance,
@@ -1482,6 +1499,8 @@ where
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<T, M> embedded_io::Read for UartRx<'_, M, T>
 where
     T: Instance,
@@ -1500,6 +1519,8 @@ where
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<T, M> embedded_io::ReadReady for Uart<'_, M, T>
 where
     T: Instance,
@@ -1510,6 +1531,8 @@ where
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<T, M> embedded_io::ReadReady for UartRx<'_, M, T>
 where
     T: Instance,
@@ -1520,6 +1543,8 @@ where
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<T, M> embedded_io::Write for Uart<'_, M, T>
 where
     T: Instance,
@@ -1534,6 +1559,8 @@ where
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<T, M> embedded_io::Write for UartTx<'_, M, T>
 where
     T: Instance,
@@ -1891,6 +1918,8 @@ where
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<T> embedded_io_async::Read for Uart<'_, Async, T>
 where
     T: Instance,
@@ -1903,6 +1932,8 @@ where
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<T> embedded_io_async::Read for UartRx<'_, Async, T>
 where
     T: Instance,
@@ -1915,6 +1946,8 @@ where
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<T> embedded_io_async::Write for Uart<'_, Async, T>
 where
     T: Instance,
@@ -1928,6 +1961,8 @@ where
     }
 }
 
+#[cfg(any(doc, feature = "unstable"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
 impl<T> embedded_io_async::Write for UartTx<'_, Async, T>
 where
     T: Instance,