examples, format

crates/servicepoint/src/connection.rs

@@ -49,25 +49,9 @@ impl Connection {
     /// # use servicepoint::{Command, CompressionCode, Grid, PixelGrid};
     /// # let connection = servicepoint::Connection::open("172.23.42.29:2342")
     /// #     .expect("connection failed");
-    ///
     ///  // turn off all pixels on display
     ///  connection.send(Command::Clear)
     ///     .expect("send failed");
-    ///
-    ///  // turn on all pixels in a grid
-    ///  let mut pixels = PixelGrid::max_sized();
-    ///  pixels.fill(true);
-    ///
-    ///  // create command to send pixels
-    ///  let command = Command::BitmapLinearWin(
-    ///     servicepoint::Origin::new(0, 0),
-    ///     pixels,
-    ///     CompressionCode::Uncompressed
-    ///  );
-    ///
-    ///  // send command to display
-    ///  connection.send(command)
-    ///     .expect("send failed");
     /// ```
     pub fn send(
         &self,

crates/servicepoint/src/lib.rs

@@ -1,4 +1,32 @@
 //! Abstractions for the UDP protocol of the CCCB servicepoint display.
+//!
+//! # Examples
+//!
+//! ```rust
+//! use servicepoint::{Command, CompressionCode, Grid, PixelGrid};
+//!
+//! let connection = servicepoint::Connection::open("172.23.42.29:2342")
+//!     .expect("connection failed");
+//!
+//!  // turn off all pixels on display
+//!  connection.send(Command::Clear)
+//!     .expect("send failed");
+//!
+//!  // turn on all pixels in a grid
+//!  let mut pixels = PixelGrid::max_sized();
+//!  pixels.fill(true);
+//!
+//!  // create command to send pixels
+//!  let command = Command::BitmapLinearWin(
+//!     servicepoint::Origin::new(0, 0),
+//!     pixels,
+//!     CompressionCode::Uncompressed
+//!  );
+//!
+//!  // send command to display
+//!  connection.send(command)
+//!     .expect("send failed");
+//! ```
 
 use std::time::Duration;
 
@@ -34,22 +62,76 @@ mod primitive_grid;
 /// size of a single tile in one dimension
 pub const TILE_SIZE: usize = 8;
 
-/// tile count in the x-direction
+/// Display tile count in the x-direction
+///
+/// # Examples
+///
+/// ```rust
+/// # use servicepoint::{Cp437Grid, TILE_HEIGHT, TILE_WIDTH};
+/// let grid = Cp437Grid::new(TILE_WIDTH, TILE_HEIGHT);
+/// ```
 pub const TILE_WIDTH: usize = 56;
 
-/// tile count in the y-direction
+/// Display tile count in the y-direction
+/// 
+/// # Examples
+///
+/// ```rust
+/// # use servicepoint::{Cp437Grid, TILE_HEIGHT, TILE_WIDTH};
+/// let grid = Cp437Grid::new(TILE_WIDTH, TILE_HEIGHT);
+/// ```
 pub const TILE_HEIGHT: usize = 20;
 
-/// screen width in pixels
+/// Display width in pixels
+/// 
+/// # Examples
+///
+/// ```rust
+/// # use servicepoint::{PIXEL_HEIGHT, PIXEL_WIDTH, PixelGrid};
+/// let grid = PixelGrid::new(PIXEL_WIDTH, PIXEL_HEIGHT);
+/// ```
 pub const PIXEL_WIDTH: usize = TILE_WIDTH * TILE_SIZE;
 
-/// screen height in pixels
+/// Display height in pixels
+///
+/// # Examples
+///
+/// ```rust
+/// # use servicepoint::{PIXEL_HEIGHT, PIXEL_WIDTH, PixelGrid};
+/// let grid = PixelGrid::new(PIXEL_WIDTH, PIXEL_HEIGHT);
+/// ```
 pub const PIXEL_HEIGHT: usize = TILE_HEIGHT * TILE_SIZE;
 
 /// pixel count on whole screen
 pub const PIXEL_COUNT: usize = PIXEL_WIDTH * PIXEL_HEIGHT;
 
 /// Actual hardware limit is around 28-29ms/frame. Rounded up for less dropped packets.
+///
+/// # Examples
+///
+/// ```rust
+/// # use std::time::Instant;
+/// # use servicepoint::{Command, CompressionCode, FRAME_PACING, Origin, PixelGrid};
+/// # let connection = servicepoint::Connection::open("172.23.42.29:2342")
+/// #     .expect("connection failed");
+/// # let pixels = PixelGrid::max_sized();
+/// loop {
+///    let start = Instant::now();
+///
+///    // Change pixels here
+///
+///    connection.send(Command::BitmapLinearWin(
+///            Origin::new(0,0), 
+///            pixels, 
+///            CompressionCode::Lzma
+///        ))
+///        .expect("send failed");
+///
+///    // warning: will crash if resulting duration is negative, e.g. when resuming from standby
+///    std::thread::sleep(FRAME_PACING - start.elapsed());
+///    # break; // prevent doctest from hanging
+/// }
+/// ```
 pub const FRAME_PACING: Duration = Duration::from_millis(30);
 
 // include README.md in doctest

crates/servicepoint_binding_c/src/brightness_grid.rs

@@ -2,8 +2,8 @@
 //!
 //! prefix `sp_brightness_grid_`
 
+use servicepoint::{Brightness, BrightnessGrid, DataRef, Grid, PrimitiveGrid};
 use std::intrinsics::transmute;
-use servicepoint::{BrightnessGrid, DataRef, Grid, PrimitiveGrid, Brightness};
 
 use crate::c_slice::CByteSlice;
 
@@ -26,7 +26,9 @@ pub unsafe extern "C" fn sp_brightness_grid_new(
     width: usize,
     height: usize,
 ) -> *mut CBrightnessGrid {
-    Box::into_raw(Box::new(CBrightnessGrid(BrightnessGrid::new(width, height))))
+    Box::into_raw(Box::new(CBrightnessGrid(BrightnessGrid::new(
+        width, height,
+    ))))
 }
 
 /// Loads a `BrightnessGrid` with the specified dimensions from the provided data.
@@ -52,8 +54,8 @@ pub unsafe extern "C" fn sp_brightness_grid_load(
 ) -> *mut CBrightnessGrid {
     let data = std::slice::from_raw_parts(data, data_length);
     let grid = PrimitiveGrid::load(width, height, data);
-    let grid = BrightnessGrid::try_from(grid)
+    let grid =
-        .expect("invalid brightness value");
+        BrightnessGrid::try_from(grid).expect("invalid brightness value");
     Box::into_raw(Box::new(CBrightnessGrid(grid)))
 }
 
@@ -84,7 +86,9 @@ pub unsafe extern "C" fn sp_brightness_grid_clone(
 /// - `this` is not used concurrently or after this call
 /// - `this` was not passed to another consuming function, e.g. to create a `Command`
 #[no_mangle]
-pub unsafe extern "C" fn sp_brightness_grid_dealloc(this: *mut CBrightnessGrid) {
+pub unsafe extern "C" fn sp_brightness_grid_dealloc(
+    this: *mut CBrightnessGrid,
+) {
     _ = Box::from_raw(this);
 }
 
@@ -141,8 +145,8 @@ pub unsafe extern "C" fn sp_brightness_grid_set(
     y: usize,
     value: u8,
 ) {
-    let brightness = Brightness::try_from(value)
+    let brightness =
-        .expect("invalid brightness value");
+        Brightness::try_from(value).expect("invalid brightness value");
     (*this).0.set(x, y, brightness);
 }
 
@@ -160,9 +164,12 @@ pub unsafe extern "C" fn sp_brightness_grid_set(
 /// - `this` points to a valid `BrightnessGrid`
 /// - `this` is not written to or read from concurrently
 #[no_mangle]
-pub unsafe extern "C" fn sp_brightness_grid_fill(this: *mut CBrightnessGrid, value: u8) {
+pub unsafe extern "C" fn sp_brightness_grid_fill(
-    let brightness = Brightness::try_from(value)
+    this: *mut CBrightnessGrid,
-        .expect("invalid brightness value");
+    value: u8,
+) {
+    let brightness =
+        Brightness::try_from(value).expect("invalid brightness value");
     (*this).0.fill(brightness);
 }
 
@@ -178,7 +185,9 @@ pub unsafe extern "C" fn sp_brightness_grid_fill(this: *mut CBrightnessGrid, val
 ///
 /// - `this` points to a valid `BrightnessGrid`
 #[no_mangle]
-pub unsafe extern "C" fn sp_brightness_grid_width(this: *const CBrightnessGrid) -> usize {
+pub unsafe extern "C" fn sp_brightness_grid_width(
+    this: *const CBrightnessGrid,
+) -> usize {
     (*this).0.width()
 }
 
@@ -194,7 +203,9 @@ pub unsafe extern "C" fn sp_brightness_grid_width(this: *const CBrightnessGrid)
 ///
 /// - `this` points to a valid `BrightnessGrid`
 #[no_mangle]
-pub unsafe extern "C" fn sp_brightness_grid_height(this: *const CBrightnessGrid) -> usize {
+pub unsafe extern "C" fn sp_brightness_grid_height(
+    this: *const CBrightnessGrid,
+) -> usize {
     (*this).0.height()
 }
 

crates/servicepoint_binding_c/src/cp437_grid.rs

@@ -188,7 +188,9 @@ pub unsafe extern "C" fn sp_cp437_grid_width(this: *const CCp437Grid) -> usize {
 ///
 /// - `this` points to a valid `Cp437Grid`
 #[no_mangle]
-pub unsafe extern "C" fn sp_cp437_grid_height(this: *const CCp437Grid) -> usize {
+pub unsafe extern "C" fn sp_cp437_grid_height(
+    this: *const CCp437Grid,
+) -> usize {
     (*this).0.height()
 }