Merge pull request #122 from videbar/update-non-blocking-display-docu…

…mentation

Updated non-blocking display documenation and added Changelog entry

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+- Fix faulty doc test in `blocking.rs`
+- Update the non-blocking display documentation to better explain when methods
+ should be called from within a critical section
 - Bump example dependencies to latest versions to fix build
 - Update examples to use RTIC 1.0
 - Add ADC for micro:bit V1

microbit-common/src/display/blocking.rs

@@ -39,6 +39,15 @@
 //! connector. That means that
 //!
 //! ```no_run
+//! # use microbit_common as microbit;
+//! # use microbit::{
+//! # Board,
+//! # hal,
+//! # display::blocking::Display,
+//! # };
+//! # let board = Board::take().unwrap();
+//! # let mut timer = hal::Timer::new(board.TIMER0);
+//! # let mut display = Display::new(board.display_pins);
 //! display.show(
 //! &mut timer,
 //! [

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

@@ -211,7 +211,10 @@ impl<T: Instance> Display<T> {
  /// Call this in an interrupt handler for the timer you're using. This method
  /// takes care of updating the LED display and clearing the timer's event registers
  ///
- /// This must be called from within a [critical
+ /// This may be called at any time, so long as the code calling it is not interrupting, or
+ /// interruptable by `tiny_led_matrix::Display::handle_event()`. Within safe code, the borrow
+ /// checker ensures that this requirement is fulfilled. When writing unsafe code, this method
+ /// should be called from within a [critical
  /// section](https://docs.rs/cortex-m/0.7.2/cortex_m/interrupt/fn.free.html).
  pub fn handle_display_event(&mut self) {
  self.display
@@ -220,7 +223,10 @@ impl<T: Instance> Display<T> {
 
  /// Show a new image
  ///
- /// This must be called from within a [critical
+ /// This may be called at any time, so long as the code calling it is not interrupting, or
+ /// interruptable by `tiny_led_matrix::Display::handle_event()`. Within safe code, the borrow
+ /// checker ensures that this requirement is fulfilled. When writing unsafe code, this method
+ /// should be called from within a [critical
  /// section](https://docs.rs/cortex-m/0.7.2/cortex_m/interrupt/fn.free.html).
  ///
  /// ## Example
@@ -241,7 +247,10 @@ impl<T: Instance> Display<T> {
 
  /// Clear the display
  ///
- /// This must be called from within a [critical
+ /// This may be called at any time, so long as the code calling it is not interrupting, or
+ /// interruptable by `tiny_led_matrix::Display::handle_event()`. Within safe code, the borrow
+ /// checker ensures that this requirement is fulfilled. When writing unsafe code, this method
+ /// should be called from within a [critical
  /// section](https://docs.rs/cortex-m/0.7.2/cortex_m/interrupt/fn.free.html).
  pub fn clear(&mut self) {
  self.display.set_frame(&MicrobitFrame::default());
@@ -253,7 +262,10 @@ impl<T: Instance> Display<T> {
  /// This may be useful if performance is a concern as calling `set` on the frame
  /// can be done outside the critical section.
  ///
- /// This must be called from within a [critical
+ /// This may be called at any time, so long as the code calling it is not interrupting, or
+ /// interruptable by `tiny_led_matrix::Display::handle_event()`. Within safe code, the borrow
+ /// checker ensures that this requirement is fulfilled. When writing unsafe code, this method
+ /// should be called from within a [critical
  /// section](https://docs.rs/cortex-m/0.7.2/cortex_m/interrupt/fn.free.html).
  ///
  /// ## Example