more examples and documentation

crates/servicepoint/src/command.rs

@@ -15,10 +15,44 @@ pub type Offset = usize;
 /// The encoding is currently not enforced.
 pub type Cp437Grid = PrimitiveGrid<u8>;
 
-/// A command to send to the display.
+/// A low-level display command.
+///
+/// This struct and associated functions implement the UDP protocol for the display.
+///
+/// To send a `Command`, use a `Connection`.
+///
+/// # Examples
+///
+/// ```rust
+/// # use servicepoint::{Brightness, Command, Connection, Packet};
+///
+/// // create command
+/// let command = Command::Brightness(Brightness::MAX);
+///
+/// // turn command into Packet
+/// let packet: Packet = command.clone().into();
+///
+/// // read command from packet
+/// let round_tripped = Command::try_from(packet).unwrap();
+///
+/// // round tripping produces exact copy
+/// assert_eq!(command, round_tripped);
+///
+/// // send command
+/// # let connection = Connection::open("127.0.0.1:2342").unwrap();
+/// connection.send(command).unwrap();
+/// ```
 #[derive(Debug, Clone, PartialEq)]
 pub enum Command {
     /// Set all pixels to the off state. Does not affect brightness.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use servicepoint::{Command, Connection};
+    /// # let connection = Connection::open("127.0.0.1:2342").unwrap();
+    /// connection.send(Command::Clear).unwrap();
+    /// ```
     Clear,
 
     /// Show text on the screen.
@@ -27,12 +61,31 @@ pub enum Command {
     ///     The library does not currently convert between UTF-8 and CP-437.
     ///     Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now.
     /// </div>
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use servicepoint::{Command, Connection, Cp437Grid, Origin};
+    /// # let connection = Connection::open("127.0.0.1:2342").unwrap();
+    /// let chars = ['H', 'e', 'l', 'l', 'o', 'W', 'o', 'r', 'l', 'd'].map(move |c| c as u8);
+    /// let grid = Cp437Grid::load(5, 2, &chars);
+    /// connection.send(Command::Cp437Data(Origin::new(2, 2), grid)).unwrap();
+    /// ```
     Cp437Data(Origin<Tiles>, Cp437Grid),
 
     /// Sets a window of pixels to the specified values
     BitmapLinearWin(Origin<Pixels>, PixelGrid, CompressionCode),
 
     /// Set the brightness of all tiles to the same value.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use servicepoint::{Brightness, Command, Connection};
+    /// # let connection = Connection::open("127.0.0.1:2342").unwrap();
+    /// let command = Command::Brightness(Brightness::MAX);
+    /// connection.send(command).unwrap();
+    /// ```
     Brightness(Brightness),
 
     /// Set the brightness of individual tiles in a rectangular area of the display.
@@ -73,17 +126,43 @@ pub enum Command {
     /// Kills the udp daemon on the display, which usually results in a restart.
     ///
     /// Please do not send this in your normal program flow.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use servicepoint::{Command, Connection};
+    /// # let connection = Connection::open("127.0.0.1:2342").unwrap();
+    /// connection.send(Command::HardReset).unwrap();
+    /// ```
     HardReset,
 
     /// <div class="warning">Untested</div>
     ///
     /// Slowly decrease brightness until off or something like that?
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use servicepoint::{Command, Connection};
+    /// # let connection = Connection::open("127.0.0.1:2342").unwrap();
+    /// connection.send(Command::FadeOut).unwrap();
+    /// ```
     FadeOut,
 
-    #[deprecated]
     /// Legacy command code, gets ignored by the real display.
     ///
     /// Might be useful as a noop package.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use servicepoint::{Command, Connection};
+    /// # let connection = Connection::open("127.0.0.1:2342").unwrap();
+    /// // this sends a packet that does nothing
+    /// # #[allow(deprecated)]
+    /// connection.send(Command::BitmapLegacy).unwrap();
+    /// ```
+    #[deprecated]
     BitmapLegacy,
 }
 

crates/servicepoint/src/compression_code.rs

@@ -1,4 +1,17 @@
 /// Specifies the kind of compression to use. Availability depends on features.
+///
+/// # Examples
+///
+/// ```rust
+/// # use servicepoint::{Command, CompressionCode, Origin, PixelGrid};
+/// // create command without payload compression
+/// # let pixels = PixelGrid::max_sized();
+/// _ = Command::BitmapLinearWin(Origin::new(0, 0), pixels, CompressionCode::Uncompressed);
+///
+/// // create command with payload compressed with lzma and appropriate header flags
+/// # let pixels = PixelGrid::max_sized();
+/// _ = Command::BitmapLinearWin(Origin::new(0, 0), pixels, CompressionCode::Lzma);
+/// ```
 #[repr(u16)]
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum CompressionCode {

crates/servicepoint/src/connection.rs

@@ -6,6 +6,15 @@ use log::{debug, info};
 use crate::Packet;
 
 /// A connection to the display.
+///
+/// # Examples
+/// ```rust
+/// # use servicepoint::Command;
+/// let connection = servicepoint::Connection::open("172.23.42.29:2342")
+///     .expect("connection failed");
+///  connection.send(Command::Clear)
+///     .expect("send failed");
+/// ```
 pub struct Connection {
     socket: UdpSocket,
 }

crates/servicepoint/src/data_ref.rs

@@ -4,6 +4,9 @@
 /// metadata needed.
 pub trait DataRef<T> {
     /// Get the underlying bytes writable.
+    ///
+    /// Note that depending on the struct this is implemented on, writing invalid values here might
+    /// lead to panics later in the lifetime of the program or on the receiving side.
     fn data_ref_mut(&mut self) -> &mut [T];
 
     /// Get the underlying bytes read-only.

crates/servicepoint/src/lib.rs

@@ -5,13 +5,17 @@
 //! ```rust
 //! use servicepoint::{Command, CompressionCode, Grid, PixelGrid};
 //!
-//! let connection = servicepoint::Connection::open("172.23.42.29:2342")
+//! let connection = servicepoint::Connection::open("127.0.0.1:2342")
 //!     .expect("connection failed");
 //!
 //!  // turn off all pixels on display
 //!  connection.send(Command::Clear)
 //!     .expect("send failed");
+//! ```
 //!
+//! ```rust
+//! # use servicepoint::{Command, CompressionCode, Grid, PixelGrid};
+//! # let connection = servicepoint::Connection::open("127.0.0.1:2342").expect("connection failed");
 //!  // turn on all pixels in a grid
 //!  let mut pixels = PixelGrid::max_sized();
 //!  pixels.fill(true);
@@ -24,8 +28,7 @@
 //!  );
 //!
 //!  // send command to display
-//!  connection.send(command)
-//!     .expect("send failed");
+//!  connection.send(command).expect("send failed");
 //! ```
 
 use std::time::Duration;
@@ -73,7 +76,7 @@ pub const TILE_SIZE: usize = 8;
 pub const TILE_WIDTH: usize = 56;
 
 /// Display tile count in the y-direction
-/// 
+///
 /// # Examples
 ///
 /// ```rust
@@ -83,7 +86,7 @@ pub const TILE_WIDTH: usize = 56;
 pub const TILE_HEIGHT: usize = 20;
 
 /// Display width in pixels
-/// 
+///
 /// # Examples
 ///
 /// ```rust
@@ -121,8 +124,8 @@ pub const PIXEL_COUNT: usize = PIXEL_WIDTH * PIXEL_HEIGHT;
 ///    // Change pixels here
 ///
 ///    connection.send(Command::BitmapLinearWin(
-///            Origin::new(0,0), 
-///            pixels, 
+///            Origin::new(0,0),
+///            pixels,
 ///            CompressionCode::Lzma
 ///        ))
 ///        .expect("send failed");