Merge pull request #36 from robyoung/docs-improvements

Various docs improvements

Author: therealprof

src/display/mod.rs

@@ -1,8 +1,8 @@
-//! Support for the 5×5 LED display.
+//! Non-blocking support for the 5×5 LED display.
 //!
 //! # Scope
 //!
-//! Together with `tiny-led-matrix`, this module provides:
+//! Together with [`tiny-led-matrix`](tiny_led_matrix), this module provides:
 //! - support for driving the LED display from a timer interrupt
 //! - ten levels of brightness for each LED
 //! - simple 5×5 greyscale and black-and-white image types.
@@ -13,8 +13,49 @@
 //!
 //! # Example
 //!
-//! `examples/led_nonblocking.rs` demonstrates the main features of this
-//! module.
+//! This shows general usage but is not a working example.
+//! For a working exaple see `examples/led_nonblocking.rs`.
+//!
+//! ```no_run
+//! // in your main function
+//! {
+//!     let p = pac::Peripherals::take().unwrap();
+//!     let mut timer = MicrobitDisplayTimer::new(p.TIMER1);
+//!     let p0parts = P0Parts::new(p.GPIO);
+//!     let mut pins = display_pins!(p0parts);
+//!     display::initialise_display(&mut timer, &mut pins);
+//!     let display = Display::new();
+//!
+//!     static mut FRAME: MicrobitFrame = MicrobitFrame::const_default();
+//!
+//!     loop {
+//!         FRAME.set(GreyscaleImage::new(&[
+//!             [0, 7, 0, 7, 0],
+//!             [7, 0, 7, 0, 7],
+//!             [7, 0, 0, 0, 7],
+//!             [0, 7, 0, 7, 0],
+//!             [0, 0, 7, 0, 0],
+//!         ]));
+//!         display.set_frame(&FRAME);
+//!         timer2.delay_ms(1000);
+//!
+//!         FRAME.set(GreyscaleImage::new(&[
+//!             [0, 0, 0, 0, 0],
+//!             [0, 0, 0, 0, 0],
+//!             [0, 0, 0, 0, 0],
+//!             [0, 0, 0, 0, 0],
+//!             [0, 0, 0, 0, 0],
+//!         ]));
+//!         display.set_frame(&FRAME);
+//!         timer2.delay_ms(1000);
+//!     }
+//! }
+//!
+//! // in a timer interrupt
+//! {
+//!     display::handle_display_event(display, timer, pins);
+//! }
+//! ```
 //!
 //! # Coordinate system
 //!
@@ -52,8 +93,8 @@
 //!
 //! The [`image`] submodule provides two static image types implementing
 //! `Render`:
-//! - [`GreyscaleImage`], allowing all 9 levels (using one byte for each LED)
-//! - [`BitImage`], allowing only 'on' and 'off' (using five bytes)
+//! - [`GreyscaleImage`](image::GreyscaleImage), allowing all 9 levels (using one byte for each LED)
+//! - [`BitImage`](image::BitImage), allowing only 'on' and 'off' (using five bytes)
 //!
 //! # Display
 //!
@@ -101,7 +142,7 @@
 //! * create a [`MicrobitDisplayTimer`] struct, passing the timer you chose to
 //! [`MicrobitDisplayTimer::new()`]
 //! * call [`initialise_display()`], passing it the `MicrobitDisplayTimer` and the
-//! [`crate::led::Pins`]
+//! [`crate::gpio::DisplayPins`]
 //! * create a [`Display`] struct (a `Display<MicrobitFrame>`).
 //!
 //! In an interrupt handler for the timer, call [`handle_display_event()`].

src/gpio.rs

@@ -1,7 +1,7 @@
 //! Named GPIO pin types
 //!
 //! This module maps the GPIO pin names as described in the
-//! [v1.5 schematic](https://github.com/bbcmicrobit/hardware/tree/master/V1.5).
+//! [Pins and Signals section of the micro:bit site](https://tech.microbit.org/hardware/edgeconnector/#pins-and-signals)
 //! Where appropriate the pins are restricted with the appropriate `MODE`
 //! from `nrf-hal`.
 #![allow(clippy::upper_case_acronyms, missing_docs)]

src/led.rs

@@ -1,5 +1,42 @@
-//! On-board user LEDs
-
+//! Blocking support for the 5x5 LED display.
+//!
+//! This module provides a simple blocking interface
+//! to the on board 5x5 LED display. If you need a more sophisticated
+//! or non-blocking interface use the [`display`](crate::display) module.
+//!
+//! # Example
+//!
+//! ```no_run
+//! use microbit::{
+//!     display_pins,
+//!     hal::{gpio::p0::Parts, prelude::*, Timer},
+//! };
+//! // take the peripherals
+//! let p = microbit::pac::Peripherals::take().unwrap();
+//! // make a timer
+//! let mut timer = Timer::new(p.TIMER0);
+//! // split off the p0::Parts
+//! let p0parts = Parts::new(p.GPIO);
+//! // create the DisplayPins struct
+//! let pins = display_pins!(p0parts);
+//! // create the Display
+//! let mut leds = led::Display::new(pins);
+//! // and light up some LEDs
+//! let heart = [
+//!     [0, 1, 0, 1, 0],
+//!     [1, 0, 1, 0, 1],
+//!     [1, 0, 0, 0, 1],
+//!     [0, 1, 0, 1, 0],
+//!     [0, 0, 1, 0, 0],
+//! ];
+//! loop {
+//!     leds.display(&mut timer, heart, 1000);
+//!     leds.clear();
+//!     timer.delay_ms(250);
+//! }
+//! ```
+//!
+//! See a working example at `examples/led_blocking.rs`
 use crate::hal::{
     gpio::{Output, Pin, PushPull},
     prelude::*,
@@ -21,16 +58,18 @@ const LED_LAYOUT: [[(usize, usize); 5]; 5] = [
     [(2, 2), (1, 6), (2, 0), (1, 5), (2, 1)],
 ];
 
-/// Array of all the LEDs in the 5x5 display on the board
+/// Blocking interface to the on board LED display
 pub struct Display {
     delay_ms: u32,
     rows: [LED; 3],
     cols: [LED; 9],
 }
 
 impl Display {
-    /// Initializes all the user LEDs
-    #[allow(clippy::too_many_arguments)]
+    /// Initialise display
+    ///
+    /// The [`display_pins!`](crate::display_pins) macro can be used
+    /// to create [`DisplayPins`].
     pub fn new(pins: DisplayPins) -> Self {
         let mut retval = Display {
             delay_ms: DEFAULT_DELAY_MS,

src/lib.rs

@@ -9,13 +9,11 @@ pub use hal::pac;
 pub use hal::pac::Peripherals;
 pub use nrf51_hal as hal;
 
-pub use nb::*;
-
 pub mod display;
 pub mod gpio;
 pub mod led;
 
-/// Create a [Uart](hal::uart::Uart] client with the default pins
+/// Create a [Uart](hal::uart::Uart) client with the default pins
 #[macro_export]
 macro_rules! serial_port {
     ( $gpio:expr, $uart:expr, $speed:expr ) => {{