add links to documentation, add some docs

crates/servicepoint/src/command.rs

@@ -18,13 +18,36 @@ pub type Cp437Grid = PrimitiveGrid<u8>;
 ///
 /// This struct and associated functions implement the UDP protocol for the display.
 ///
-/// To send a `Command`, use a `Connection`.
+/// To send a [Command], use a [connection][crate::Connection].
+///
+/// # Available commands
+///
+/// To send text, take a look at [Command::Cp437Data].
+///
+/// To draw pixels, the easiest command to use is [Command::BitmapLinearWin].
+///
+/// The other BitmapLinear-Commands operate on a region of pixel memory directly.
+/// [Command::BitmapLinear] overwrites a region.
+/// [Command::BitmapLinearOr], [Command::BitmapLinearAnd] and [Command::BitmapLinearXor] apply logical operations per pixel.
+///
+/// Out of bounds operations may be truncated or ignored by the display.
+///
+/// # Compression
+///
+/// Some commands can contain compressed payloads.
+/// To get started, use [CompressionCode::Uncompressed].
+///
+/// If you want to archive the best performance (e.g. latency),
+/// you can try the different compression algorithms for your hardware and use case.
+///
+/// In memory, the payload is not compressed in the [Command].
+/// Payload (de-)compression happens when converting the [Command] into a [Packet] or vice versa.
 ///
 /// # Examples
 ///
 /// ```rust
 /// # use servicepoint::{Brightness, Command, Connection, Packet};
-///
+/// #
 /// // create command
 /// let command = Command::Brightness(Brightness::MAX);
 ///
@@ -56,6 +79,8 @@ pub enum Command {
 
     /// Show text on the screen.
     ///
+    /// The text is sent in the form of a 2D grid of characters.
+    ///
     /// <div class="warning">
     ///     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.
@@ -72,7 +97,29 @@ pub enum Command {
     /// ```
     Cp437Data(Origin<Tiles>, Cp437Grid),
 
-    /// Sets a window of pixels to the specified values
+    /// Overwrites a rectangular region of pixels.
+    ///
+    /// Origin coordinates must be divisible by 8.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use servicepoint::{Command, CompressionCode, Grid, PixelGrid};
+    /// # let connection = servicepoint::Connection::Fake;
+    /// #
+    /// let mut pixels = PixelGrid::max_sized();
+    /// // draw something to the pixels here
+    /// # pixels.set(2, 5, true);
+    ///
+    /// // create command to send pixels
+    /// let command = Command::BitmapLinearWin(
+    ///    servicepoint::Origin::new(0, 0),
+    ///    pixels,
+    ///    CompressionCode::Uncompressed
+    /// );
+    ///
+    /// connection.send(command).expect("send failed");
+    /// ```
     BitmapLinearWin(Origin<Pixels>, PixelGrid, CompressionCode),
 
     /// Set the brightness of all tiles to the same value.
@@ -95,7 +142,7 @@ pub enum Command {
     /// The screen will continuously overwrite more pixel data without regarding the offset, meaning
     /// once the starting row is full, overwriting will continue on column 0.
     ///
-    /// The contained `BitVec` is always uncompressed.
+    /// The contained [BitVec] is always uncompressed.
     BitmapLinear(Offset, SpBitVec, CompressionCode),
 
     /// Set pixel data according to an and-mask starting at the offset.
@@ -103,7 +150,7 @@ pub enum Command {
     /// The screen will continuously overwrite more pixel data without regarding the offset, meaning
     /// once the starting row is full, overwriting will continue on column 0.
     ///
-    /// The contained `BitVec` is always uncompressed.
+    /// The contained [BitVec] is always uncompressed.
     BitmapLinearAnd(Offset, SpBitVec, CompressionCode),
 
     /// Set pixel data according to an or-mask starting at the offset.
@@ -111,7 +158,7 @@ pub enum Command {
     /// The screen will continuously overwrite more pixel data without regarding the offset, meaning
     /// once the starting row is full, overwriting will continue on column 0.
     ///
-    /// The contained `BitVec` is always uncompressed.
+    /// The contained [BitVec] is always uncompressed.
     BitmapLinearOr(Offset, SpBitVec, CompressionCode),
 
     /// Set pixel data according to a xor-mask starting at the offset.
@@ -119,7 +166,7 @@ pub enum Command {
     /// The screen will continuously overwrite more pixel data without regarding the offset, meaning
     /// once the starting row is full, overwriting will continue on column 0.
     ///
-    /// The contained `BitVec` is always uncompressed.
+    /// The contained [BitVec] is always uncompressed.
     BitmapLinearXor(Offset, SpBitVec, CompressionCode),
 
     /// Kills the udp daemon on the display, which usually results in a restart.
@@ -166,7 +213,7 @@ pub enum Command {
 }
 
 #[derive(Debug)]
-/// Err values for `Command::try_from`.
+/// Err values for [Command::try_from].
 #[derive(PartialEq)]
 pub enum TryFromPacketError {
     /// the contained command code does not correspond to a known command
@@ -188,7 +235,7 @@ pub enum TryFromPacketError {
 impl TryFrom<Packet> for Command {
     type Error = TryFromPacketError;
 
-    /// Try to interpret the `Packet` as one containing a `Command`
+    /// Try to interpret the [Packet] as one containing a [Command]
     fn try_from(packet: Packet) -> Result<Self, Self::Error> {
         let Packet {
             header: Header {

crates/servicepoint/src/command_code.rs

@@ -1,4 +1,4 @@
-/// The u16 command codes used for the `Commands`.
+/// The u16 command codes used for the [Command]s.
 #[repr(u16)]
 #[derive(Debug, Copy, Clone)]
 pub(crate) enum CommandCode {

crates/servicepoint/src/connection.rs

@@ -7,6 +7,8 @@ use crate::Packet;
 
 /// A connection to the display.
 ///
+/// Used to send [Packets][Packet] or [Commands][crate::Command].
+///
 /// # Examples
 /// ```rust
 /// let connection = servicepoint::Connection::open("172.23.42.29:2342")

crates/servicepoint/src/lib.rs

@@ -1,5 +1,9 @@
 //! Abstractions for the UDP protocol of the CCCB servicepoint display.
 //!
+//! Your starting point is a [Connection] to the display.
+//! With a connection, you can send [Command]s.
+//! When received, the display will update the state of the pixels.
+//!
 //! # Examples
 //!
 //! ```rust

crates/servicepoint/src/origin.rs

@@ -11,7 +11,7 @@ pub struct Origin<Unit: DisplayUnit> {
 }
 
 impl<Unit: DisplayUnit> Origin<Unit> {
-    /// Create a new `Origin` instance for the provided position.
+    /// Create a new [Origin] instance for the provided position.
     pub fn new(x: usize, y: usize) -> Self {
         Self {
             x,

crates/servicepoint/src/packet.rs

@@ -38,6 +38,8 @@ pub type Payload = Vec<u8>;
 ///
 /// Contents should probably only be used directly to use features not exposed by the library.
 ///
+/// You may want to use [Command][crate::Command] instead.
+///
 /// # Examples
 ///
 /// Converting a packet to a command and back:
@@ -46,7 +48,7 @@ pub type Payload = Vec<u8>;
 /// # use servicepoint::{Command, Packet};
 /// # let command = Command::Clear;
 /// let packet: Packet = command.into();
-/// let command: Command = Command::try_from(packet).expect("could not read packet");
+/// let command: Command = Command::try_from(packet).expect("could not read command from packet");
 /// ```
 ///
 /// Converting a packet to bytes and back:
@@ -98,9 +100,9 @@ impl From<Packet> for Vec<u8> {
 impl TryFrom<&[u8]> for Packet {
     type Error = ();
 
-    /// Tries to interpret the bytes as a `Packet`.
+    /// Tries to interpret the bytes as a [Packet].
     ///
-    /// returns: `Error` if slice is not long enough to be a `Packet`
+    /// returns: `Error` if slice is not long enough to be a [Packet]
     fn try_from(value: &[u8]) -> Result<Self, Self::Error> {
         if value.len() < size_of::<Header>() {
             return Err(());
@@ -135,7 +137,7 @@ impl TryFrom<Vec<u8>> for Packet {
 }
 
 impl From<Command> for Packet {
-    /// Move the `Command` into a `Packet` instance for sending.
+    /// Move the [Command] into a [Packet] instance for sending.
     #[allow(clippy::cast_possible_truncation)]
     fn from(value: Command) -> Self {
         match value {
@@ -210,7 +212,7 @@ impl From<Command> for Packet {
 }
 
 impl Packet {
-    /// Helper method for `BitMapLinear*`-Commands into `Packet`
+    /// Helper method for `BitMapLinear*`-Commands into [Packet]
     #[allow(clippy::cast_possible_truncation)]
     fn bitmap_linear_into_packet(
         command: CommandCode,

crates/servicepoint/src/pixel_grid.rs

@@ -13,14 +13,14 @@ pub struct PixelGrid {
 }
 
 impl PixelGrid {
-    /// Creates a new `PixelGrid` with the specified dimensions.
+    /// Creates a new [PixelGrid] with the specified dimensions.
     ///
     /// # Arguments
     ///
     /// - `width`: size in pixels in x-direction
     /// - `height`: size in pixels in y-direction
     ///
-    /// returns: `PixelGrid` initialized to all pixels off
+    /// returns: [PixelGrid] initialized to all pixels off
     ///
     /// # Panics
     ///
@@ -40,14 +40,14 @@ impl PixelGrid {
         Self::new(PIXEL_WIDTH, PIXEL_HEIGHT)
     }
 
-    /// Loads a `PixelGrid` with the specified dimensions from the provided data.
+    /// Loads a [PixelGrid] with the specified dimensions from the provided data.
     ///
     /// # Arguments
     ///
     /// - `width`: size in pixels in x-direction
     /// - `height`: size in pixels in y-direction
     ///
-    /// returns: `PixelGrid` that contains a copy of the provided data
+    /// returns: [PixelGrid] that contains a copy of the provided data
     ///
     /// # Panics
     ///
@@ -64,7 +64,7 @@ impl PixelGrid {
         }
     }
 
-    /// Iterate over all cells in `PixelGrid`.
+    /// Iterate over all cells in [PixelGrid].
     ///
     /// Order is equivalent to the following loop:
     /// ```
@@ -80,7 +80,7 @@ impl PixelGrid {
         self.bit_vec.iter().by_refs()
     }
 
-    /// Iterate over all cells in `PixelGrid` mutably.
+    /// Iterate over all cells in [PixelGrid] mutably.
     ///
     /// Order is equivalent to the following loop:
     /// ```
@@ -107,7 +107,7 @@ impl PixelGrid {
         self.bit_vec.iter_mut()
     }
 
-    /// Iterate over all rows in `PixelGrid` top to bottom.
+    /// Iterate over all rows in [PixelGrid] top to bottom.
     pub fn iter_rows(&self) -> IterRows {
         IterRows {
             pixel_grid: self,
@@ -117,7 +117,7 @@ impl PixelGrid {
 }
 
 impl Grid<bool> for PixelGrid {
-    /// Sets the value of the specified position in the `PixelGrid`.
+    /// Sets the value of the specified position in the [PixelGrid].
     ///
     /// # Arguments
     ///
@@ -139,7 +139,7 @@ impl Grid<bool> for PixelGrid {
         self.bit_vec[x + y * self.width]
     }
 
-    /// Sets the state of all pixels in the `PixelGrid`.
+    /// Sets the state of all pixels in the [PixelGrid].
     ///
     /// # Arguments
     ///
@@ -169,7 +169,7 @@ impl DataRef<u8> for PixelGrid {
 }
 
 impl From<PixelGrid> for Vec<u8> {
-    /// Turns a `PixelGrid` into the underlying `Vec<u8>`.
+    /// Turns a [PixelGrid] into the underlying [`Vec<u8>`].
     fn from(value: PixelGrid) -> Self {
         value.bit_vec.into()
     }

crates/servicepoint/src/primitive_grid.rs

@@ -14,14 +14,14 @@ pub struct PrimitiveGrid<T: PrimitiveGridType> {
 }
 
 impl<T: PrimitiveGridType> PrimitiveGrid<T> {
-    /// Creates a new `PrimitiveGrid` with the specified dimensions.
+    /// Creates a new [PrimitiveGrid] with the specified dimensions.
     ///
     /// # Arguments
     ///
     /// - width: size in x-direction
     /// - height: size in y-direction
     ///
-    /// returns: `PrimitiveGrid` initialized to default value.
+    /// returns: [PrimitiveGrid] initialized to default value.
     pub fn new(width: usize, height: usize) -> Self {
         Self {
             data: vec![Default::default(); width * height],
@@ -30,9 +30,9 @@ impl<T: PrimitiveGridType> PrimitiveGrid<T> {
         }
     }
 
-    /// Loads a `PrimitiveGrid` with the specified dimensions from the provided data.
+    /// Loads a [PrimitiveGrid] with the specified dimensions from the provided data.
     ///
-    /// returns: `PrimitiveGrid` that contains a copy of the provided data
+    /// returns: [PrimitiveGrid] that contains a copy of the provided data
     ///
     /// # Panics
     ///
@@ -47,7 +47,7 @@ impl<T: PrimitiveGridType> PrimitiveGrid<T> {
         }
     }
 
-    /// Iterate over all cells in `PrimitiveGrid`.
+    /// Iterate over all cells in [PrimitiveGrid].
     ///
     /// Order is equivalent to the following loop:
     /// ```
@@ -63,7 +63,7 @@ impl<T: PrimitiveGridType> PrimitiveGrid<T> {
         self.data.iter()
     }
 
-    /// Iterate over all rows in `PrimitiveGrid` top to bottom.
+    /// Iterate over all rows in [PrimitiveGrid] top to bottom.
     pub fn iter_rows(&self) -> IterRows<T> {
         IterRows {
             byte_grid: self,
@@ -168,7 +168,7 @@ impl<T: PrimitiveGridType> DataRef<T> for PrimitiveGrid<T> {
 }
 
 impl<T: PrimitiveGridType> From<PrimitiveGrid<T>> for Vec<T> {
-    /// Turn into the underlying `Vec<u8>` containing the rows of bytes.
+    /// Turn into the underlying [`Vec<u8>`] containing the rows of bytes.
     fn from(value: PrimitiveGrid<T>) -> Self {
         value.data
     }