Add doc examples

esp-rs · Aug 16, 2024 · 195d9b4 · 195d9b4
1 parent 6cd511b
commit 195d9b4
Show file tree

Hide file tree

Showing 4 changed files with 51 additions and 13 deletions.
diff --git a/esp-hal-embassy/src/lib.rs b/esp-hal-embassy/src/lib.rs
@@ -127,12 +127,25 @@ impl<const N: usize> TimerCollection for &'static mut [Timer; N] {
 ///
 /// The time driver can be one of a number of different options:
 ///
-/// - A [Timg] timer instance
-/// - An [Alarm] instance
-/// - An [ErasedTimer] instance
-/// - A [OneShotTimer] instance
-/// - A mutable static slice of [OneShotTimer] instances
-/// - A mutable static array of [OneShotTimer] instances
+/// - A timg `Timer` instance
+/// - A systimer `Alarm` instance
+/// - An `ErasedTimer` instance
+/// - A `OneShotTimer` instance
+/// - A mutable static slice of `OneShotTimer` instances
+/// - A mutable static array of `OneShotTimer` instances
+///
+/// # Examples
+///
+/// ```rust, no_run
+#[doc = esp_hal::before_snippet!()]
+/// use esp_hal::timg::TimerGroup;
+///
+/// let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
+/// esp_hal_embassy::init(&clocks, timg0.timer0);
+///
+/// // ... now you can spawn embassy tasks or use `Timer::after` etc.
+/// # }
+/// ```
 pub fn init(clocks: &Clocks, time_driver: impl TimerCollection) {
     EmbassyTimer::init(clocks, time_driver.timers())
 }
diff --git a/esp-hal/src/lib.rs b/esp-hal/src/lib.rs
@@ -680,7 +680,10 @@ unsafe extern "C" fn stack_chk_fail() {
 #[macro_export]
 macro_rules! before_snippet {
     () => {
-        core::include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/doc-helper/before"))
+        core::include_str!(concat!(
+            env!("CARGO_MANIFEST_DIR"),
+            "/../esp-hal/doc-helper/before"
+        ))
     };
 }
 
@@ -690,6 +693,9 @@ macro_rules! before_snippet {
 #[macro_export]
 macro_rules! before_snippet {
     () => {
-        core::include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "\\doc-helper\\before"))
+        core::include_str!(concat!(
+            env!("CARGO_MANIFEST_DIR"),
+            "\\..\\esp-hal\\doc-helper\\before"
+        ))
     };
 }
diff --git a/esp-wifi/README.md b/esp-wifi/README.md
@@ -28,7 +28,7 @@ Minimum supported Rust compiler version: 1.72.0.0
 
 ### Importing
 
-Ensure that the right features are enabled for your chip. See [Examples] for more examples.
+Ensure that the right features are enabled for your chip. See [Examples](https://github.com/esp-rs/esp-hal/tree/main/examples#examples) for more examples.
 
 ```toml
 [dependencies.esp-wifi]

diff --git a/esp-wifi/src/lib.rs b/esp-wifi/src/lib.rs
@@ -275,10 +275,29 @@ impl EspWifiTimerSource for TimeBase {
 /// The `timer` argument is a timer source that is used by the WiFi driver to
 /// schedule internal tasks. The timer source can be any of the following:
 ///
-/// - A [Timg] timer instance
-/// - An [Alarm] instance
-/// - An [ErasedTimer] instance
-/// - A [PeriodicTimer] instance
+/// - A timg `Timer` instance
+/// - A systimer `Alarm` instance
+/// - An `ErasedTimer` instance
+/// - A `OneShotTimer` instance
+///
+/// # Examples
+///
+/// ```rust, no_run
+#[doc = esp_hal::before_snippet!()]
+/// use esp_hal::{rng::Rng, timg::TimerGroup};
+/// use esp_wifi::EspWifiInitFor;
+///
+/// let timg0 = TimerGroup::new(peripherals.TIMG0, &clocks);
+/// let init = esp_wifi::initialize(
+///     EspWifiInitFor::Wifi,
+///     timg0.timer0,
+///     Rng::new(peripherals.RNG),
+///     peripherals.RADIO_CLK,
+///     &clocks,
+/// )
+/// .unwrap();
+/// # }
+/// ```
 pub fn initialize(
     init_for: EspWifiInitFor,
     timer: impl EspWifiTimerSource,