WIP: Docs improvement

examples/rng-hal/src/main.rs

@@ -36,7 +36,7 @@ fn main() -> ! {
 
         let mut seed: [u8; 16] = [0; 16];
 
-        /* Read 4 bytes of data from hardware RNG */
+        /* Read 16 bytes of data from hardware RNG */
         rng.random(&mut seed);
 
         let rng = Pcg32::from_seed(seed);

microbit-common/src/display/nonblocking/mod.rs

@@ -99,26 +99,26 @@
 //!
 //! Internally types implementing [`Render`](tiny_led_matrix::Render) aren't used directly with the [`Display`];
 //! instead they're used to update a [`MicrobitFrame`] instance which is in
-//! turn passed to the `tiny_led_matrix::Display`.
+//! turn passed to the [`tiny_led_matrix::Display`].
 //!
-//! A `MicrobitFrame` instance is a 'compiled' representation of a 5×5
+//! A [`MicrobitFrame`] instance is a 'compiled' representation of a 5×5
 //! greyscale image, in a form that's more directly usable by the display
 //! code.
 //!
 //! This is exposed in the public API so that you can construct the
-//! `MicrobitFrame` representation in code running at a low priority. Then
+//! [`MicrobitFrame`] representation in code running at a low priority. Then
 //! only [`Display::show_frame()`] has to be called in code that can't be
 //! interrupted by the display timer.
 //!
 //! ## Timer integration
 //!
 //! The [`Display`] expects to control a single timer. It can use the
-//! micro:bit's `TIMER0`, `TIMER1`, or `TIMER2`.
+//! micro:bit's [`TIMER0`](crate::hal::pac::TIMER0), [`TIMER1`](crate::hal::pac::TIMER1), or [`TIMER2`](crate::hal::pac::TIMER2).
 //!
 //! This uses a 6ms period to light each of the three internal LED rows, so
 //! that the entire display is updated every 18ms.
 //!
-//! When rendering greyscale images, the `Display` requests extra interrupts
+//! When rendering greyscale images, the [`Display`] requests extra interrupts
 //! within each 6ms period. It only requests interrupts for the greyscale
 //! levels which are actually required for what's currently being displayed.
 //!
@@ -129,7 +129,8 @@
 //!
 //! ## Usage
 //!
-//! Choose a timer to drive the display from (`TIMER0`, `TIMER1`, or `TIMER2`).
+//! Choose a timer to drive the display from [`TIMER0`](crate::hal::pac::TIMER0),
+//! [`TIMER1`](crate::hal::pac::TIMER1), or [`TIMER2`](crate::hal::pac::TIMER2).
 //!
 //! When your program starts:
 //! - create a [`Display`] struct passing the timer and
@@ -139,7 +140,7 @@
 //!
 //! To change what's displayed; pass an image ([`GreyscaleImage`] or [`BitImage`]) to [`Display::show`].
 //!
-//! You can call `show()` at any time, so long as you're not interrupting, or interruptable by,
+//! You can call [`show()`](Display::show) at any time, so long as you're not interrupting, or interruptable by,
 //! [`Display::handle_display_event()`].
 //!
 //! See [`display_rtic`](https://github.com/nrf-rs/microbit/blob/master/examples/display_rtic) or

microbit-common/src/v1/board.rs

@@ -70,10 +70,70 @@ pub struct Board {
     /// nRF51 peripheral: GPIOTE
     pub GPIOTE: pac::GPIOTE,
 
-    /// nRF51 peripheral: RADIO
+    /// nRF51 peripheral: RADIO <br>
+    /// Can be used with [`Radio::init()`](`crate::hal::ieee802154::Radio::init()`)
+    /// ```no_run
+    /// # use microbit_common as microbit;
+    /// # use microbit::{
+    /// #     Board,
+    /// #     hal::Clocks,
+    /// #     display::blocking::Display,
+    /// # };
+    /// # use embedded_hal::blocking::delay::DelayMs;
+    /// # use core::ops::Deref;
+    /// use microbit::hal::ieee802154;
+    /// // take the board
+    /// let board = Board::take().unwrap();
+    /// // setup a timer for the receiving radio messages within a certain timeframe
+    /// let mut radio_timer = microbit::hal::Timer::new(board.TIMER0);
+    /// // set the clock to a high frequency one
+    /// let clock = Clocks::new(board.CLOCK).enable_ext_hfosc();
+    /// // create the radio instance
+    /// let mut radio = ieee802154::Radio::init(board.RADIO, &clock);
+    ///
+    /// // create an empty message packet
+    /// let mut packet = ieee802154::Packet::new();
+    ///    
+    /// // Wait if a package gets received for 1.000 microseconds
+    /// match radio
+    ///     .recv_timeout(&mut packet, &mut radio_timer, 1000)
+    /// {
+    ///     // Use the received radio packet...    
+    ///     Ok(_) => {        
+    ///         if packet.deref()[0] == 2u8 { /* ... */ }
+    ///     }     
+    ///     // Expected timeout if no message was received in time
+    ///     Err(ieee802154::Error::Timeout) => {}
+    ///     Err(ieee802154::Error::Crc(error_code)) => {/* Handle crc error */}
+    /// }
+    ///
+    /// // fill the packet payload with 2 bytes of 42
+    /// packet.copy_from_slice(&[42u8;2]);
+    /// // send the radio packet
+    /// radio.send(&mut packet);
+    /// # loop {
+    /// # }
+    /// ```
     pub RADIO: pac::RADIO,
 
-    /// nRF51 peripheral: RNG
+    /// nRF51 peripheral: RNG <br>
+    /// Can be used with [`Rng::new()`](`crate::hal::rng::Rng::new()`)
+    /// ```no_run
+    /// # use microbit_common as microbit;
+    /// use microbit::{hal::{clocks, rng}, Board};
+    /// // take the board
+    /// let board = Board::take().unwrap();
+    ///
+    /// // start low frequency clock
+    /// clocks::Clocks::new(board.CLOCK).start_lfclk();
+    ///
+    /// // create a new hardware rng instance
+    /// let mut rng = rng::Rng::new(board.RNG);
+    ///
+    /// // read random u32 directly from hardware rng
+    /// let small_int = rng.random_u32();
+    /// #    loop {}
+    /// ```
     pub RNG: pac::RNG,
 
     /// nRF51 peripheral: RTC0
@@ -83,13 +143,16 @@ pub struct Board {
     /// Can be used with [`Temp::new()`](`crate::hal::temp::Temp::new()`)
     pub TEMP: pac::TEMP,
 
-    /// nRF51 peripheral: TIMER0
+    /// nRF51 peripheral: TIMER0 <br>
+    /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
     pub TIMER0: pac::TIMER0,
 
-    /// nRF51 peripheral: TIMER1
+    /// nRF51 peripheral: TIMER1 <br>
+    /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
     pub TIMER1: pac::TIMER1,
 
-    /// nRF51 peripheral: TIMER2
+    /// nRF51 peripheral: TIMER2 <br>
+    /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
     pub TIMER2: pac::TIMER2,
 
     /// nRF51 peripheral: TWI0

microbit-common/src/v2/board.rs

@@ -81,50 +81,122 @@ pub struct Board {
     /// nRF52 peripheral: GPIOTE
     pub GPIOTE: pac::GPIOTE,
 
-    /// nRF52 peripheral: PWM0
+    /// nRF52 peripheral: PWM0 <br>
+    /// Can be used with [`Pwm::new()`](`crate::hal::pwm::Pwm::new()`)
     pub PWM0: pac::PWM0,
 
-    /// nRF52 peripheral: PWM1
+    /// nRF52 peripheral: PWM1 <br>
+    /// Can be used with [`Pwm::new()`](`crate::hal::pwm::Pwm::new()`)
     pub PWM1: pac::PWM1,
 
-    /// nRF52 peripheral: PWM2
+    /// nRF52 peripheral: PWM2 <br>
+    /// Can be used with [`Pwm::new()`](`crate::hal::pwm::Pwm::new()`)
     pub PWM2: pac::PWM2,
 
-    /// nRF52 peripheral: PWM3
+    /// nRF52 peripheral: PWM3 <br>
+    /// Can be used with [`Pwm::new()`](`crate::hal::pwm::Pwm::new()`)
     pub PWM3: pac::PWM3,
 
-    /// nRF52 peripheral: RADIO
+    /// nRF52 peripheral: RADIO <br>
+    /// Can be used with [`Radio::init()`](`crate::hal::ieee802154::Radio::init()`)
+    /// ```no_run
+    /// # use microbit_common as microbit;
+    /// # use microbit::{
+    /// #     Board,
+    /// #     hal::Clocks,
+    /// #     display::blocking::Display,
+    /// # };
+    /// # use embedded_hal::blocking::delay::DelayMs;
+    /// # use core::ops::Deref;
+    /// use microbit::hal::ieee802154;
+    /// // take the board
+    /// let board = Board::take().unwrap();
+    /// // setup a timer for the receiving radio messages within a certain timeframe
+    /// let mut radio_timer = microbit::hal::Timer::new(board.TIMER0);
+    /// // set the clock to a high frequency one
+    /// let clock = Clocks::new(board.CLOCK).enable_ext_hfosc();
+    /// // create the radio instance
+    /// let mut radio = ieee802154::Radio::init(board.RADIO, &clock);
+    ///
+    /// // create an empty message packet
+    /// let mut packet = ieee802154::Packet::new();
+    ///    
+    /// // Wait if a package gets received for 1.000 microseconds
+    /// match radio
+    ///     .recv_timeout(&mut packet, &mut radio_timer, 1000)
+    /// {
+    ///     // Use the received radio packet...    
+    ///     Ok(_) => {        
+    ///         if packet.deref()[0] == 2u8 { /* ... */ }
+    ///     }     
+    ///     // Expected timeout if no message was received in time
+    ///     Err(ieee802154::Error::Timeout) => {}
+    ///     Err(ieee802154::Error::Crc(error_code)) => {/* Handle crc error */}
+    /// }
+    ///
+    /// // fill the packet payload with 2 bytes of 42
+    /// packet.copy_from_slice(&[42u8;2]);
+    /// // send the radio packet
+    /// radio.send(&mut packet);
+    /// # loop {
+    /// # }
+    /// ```
     pub RADIO: pac::RADIO,
 
-    /// nRF52 peripheral: RNG
+    /// nRF52 peripheral: RNG <br>
+    /// Can be used with [`Rng::new()`](`crate::hal::rng::Rng::new()`)
+    /// ```no_run
+    /// # use microbit_common as microbit;
+    /// use microbit::{hal::{clocks, rng}, Board};
+    /// // take the board
+    /// let board = Board::take().unwrap();
+    ///
+    /// // start low frequency clock
+    /// clocks::Clocks::new(board.CLOCK).start_lfclk();
+    ///
+    /// // create a new hardware rng instance
+    /// let mut rng = rng::Rng::new(board.RNG);
+    ///
+    /// // read random u32 directly from hardware rng
+    /// let small_int = rng.random_u32();
+    /// #    loop {}
+    /// ```
     pub RNG: pac::RNG,
 
     /// nRF52 peripheral: RTC0
     pub RTC0: pac::RTC0,
-
+  
     /// nRF52 peripheral: RTC1
     pub RTC1: pac::RTC1,
 
     /// nRF52 peripheral: RTC2
-    pub RTC2: pac::RTC2,
+    pub RTC2: pac::RTC2,  
+
+    /// nRF52 peripheral: SAADC
+    pub SAADC: pac::SAADC,
 
     /// nRF52 peripheral: TEMP <br>
     /// Can be used with [`Temp::new()`](`crate::hal::temp::Temp::new()`)
     pub TEMP: pac::TEMP,
 
-    /// nRF52 peripheral: TIMER0
+    /// nRF52 peripheral: TIMER0 <br>
+    /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
     pub TIMER0: pac::TIMER0,
 
-    /// nRF52 peripheral: TIMER1
+    /// nRF52 peripheral: TIMER1 <br>
+    /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
     pub TIMER1: pac::TIMER1,
 
-    /// nRF52 peripheral: TIMER2
+    /// nRF52 peripheral: TIMER2 <br>
+    /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
     pub TIMER2: pac::TIMER2,
 
-    /// nRF52 peripheral: TIMER3
+    /// nRF52 peripheral: TIMER3 <br>
+    /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
     pub TIMER3: pac::TIMER3,
 
-    /// nRF52 peripheral: TIMER4
+    /// nRF52 peripheral: TIMER4 <br>
+    /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
     pub TIMER4: pac::TIMER4,
 
     /// nRF52 peripheral: TWIM0
@@ -138,9 +210,6 @@ pub struct Board {
 
     /// nRF52 peripheral: UARTE1
     pub UARTE1: pac::UARTE1,
-
-    /// nRF52 peripheral: SAADC
-    pub SAADC: pac::SAADC,
 }
 
 impl Board {
@@ -253,7 +322,8 @@ impl Board {
             RNG: p.RNG,
             RTC0: p.RTC0,
             RTC1: p.RTC1,
-            RTC2: p.RTC2,
+            RTC2: p.RTC2,          
+            SAADC: p.SAADC,
             TEMP: p.TEMP,
             TIMER0: p.TIMER0,
             TIMER1: p.TIMER1,
@@ -264,7 +334,6 @@ impl Board {
             TWIS0: p.TWIS0,
             UARTE0: p.UARTE0,
             UARTE1: p.UARTE1,
-            SAADC: p.SAADC,
         }
     }
 }