add NULL checks - command

crates/servicepoint_binding_c/src/command.rs

@@ -4,7 +4,7 @@
 
 use std::ptr::null_mut;
 
-use servicepoint::{Brightness, Origin};
+use servicepoint::{Brightness, Command, Origin};
 
 use crate::{
     SPBitVec, SPBrightnessGrid, SPCompressionCode, SPCp437Grid, SPPacket,
@@ -15,7 +15,7 @@ use crate::{
 ///
 /// This struct and associated functions implement the UDP protocol for the display.
 ///
-/// To send a [SPCommand], use a `SPConnection`.
+/// To send a [SPCommand], use a [SPConnection].
 ///
 /// # Examples
 ///
@@ -31,18 +31,22 @@ impl Clone for SPCommand {
     }
 }
 
-/// Tries to turn a `SPPacket` into a [SPCommand].
+/// Tries to turn a [SPPacket] into a [SPCommand].
 ///
 /// The packet is deallocated in the process.
 ///
-/// Returns: pointer to new [SPCommand] instance or NULL
+/// Returns: pointer to new [SPCommand] instance or NULL if parsing failed.
+///
+/// # Panics
+///
+/// - when `packet` is NULL
 ///
 /// # Safety
 ///
 /// The caller has to make sure that:
 ///
-/// - `SPPacket` points to a valid instance of `SPPacket`
+/// - [SPPacket] points to a valid instance of [SPPacket]
-/// - `SPPacket` is not used concurrently or after this call
+/// - [SPPacket] is not used concurrently or after this call
 /// - the result is checked for NULL
 /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
 ///   by explicitly calling `sp_command_free`.
@@ -59,6 +63,12 @@ pub unsafe extern "C" fn sp_command_try_from_packet(
 
 /// Clones a [SPCommand] instance.
 ///
+/// returns: new [SPCommand] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `command` is NULL
+///
 /// # Safety
 ///
 /// The caller has to make sure that:
@@ -71,14 +81,17 @@ pub unsafe extern "C" fn sp_command_try_from_packet(
 pub unsafe extern "C" fn sp_command_clone(
     command: *const SPCommand,
 ) -> *mut SPCommand {
-    Box::into_raw(Box::new((*command).clone()))
+    assert!(!command.is_null());
+    let result = Box::into_raw(Box::new((*command).clone()));
+    assert!(!result.is_null());
+    result
 }
 
 /// Set all pixels to the off state.
 ///
 /// Does not affect brightness.
 ///
-/// Returns: a new `Command::Clear` instance. Will never return NULL.
+/// Returns: a new [Command::Clear] instance. Will never return NULL.
 ///
 /// # Examples
 ///
@@ -94,14 +107,16 @@ pub unsafe extern "C" fn sp_command_clone(
 ///   by explicitly calling `sp_command_free`.
 #[no_mangle]
 pub unsafe extern "C" fn sp_command_clear() -> *mut SPCommand {
-    Box::into_raw(Box::new(SPCommand(servicepoint::Command::Clear)))
+    let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::Clear)));
+    assert!(!result.is_null());
+    result
 }
 
 /// Kills the udp daemon on the display, which usually results in a restart.
 ///
 /// Please do not send this in your normal program flow.
 ///
-/// Returns: a new `Command::HardReset` instance. Will never return NULL.
+/// Returns: a new [Command::HardReset] instance. Will never return NULL.
 ///
 /// # Safety
 ///
@@ -111,7 +126,9 @@ pub unsafe extern "C" fn sp_command_clear() -> *mut SPCommand {
 ///   by explicitly calling `sp_command_free`.
 #[no_mangle]
 pub unsafe extern "C" fn sp_command_hard_reset() -> *mut SPCommand {
-    Box::into_raw(Box::new(SPCommand(servicepoint::Command::HardReset)))
+    let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::HardReset)));
+    assert!(!result.is_null());
+    result
 }
 
 /// A yet-to-be-tested command.
@@ -126,12 +143,14 @@ pub unsafe extern "C" fn sp_command_hard_reset() -> *mut SPCommand {
 ///   by explicitly calling `sp_command_free`.
 #[no_mangle]
 pub unsafe extern "C" fn sp_command_fade_out() -> *mut SPCommand {
-    Box::into_raw(Box::new(SPCommand(servicepoint::Command::FadeOut)))
+    let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::FadeOut)));
+    assert!(!result.is_null());
+    result
 }
 
 /// Set the brightness of all tiles to the same value.
 ///
-/// Returns: a new `Command::Brightness` instance. Will never return NULL.
+/// Returns: a new [Command::Brightness] instance. Will never return NULL.
 ///
 /// # Panics
 ///
@@ -149,16 +168,22 @@ pub unsafe extern "C" fn sp_command_brightness(
 ) -> *mut SPCommand {
     let brightness =
         Brightness::try_from(brightness).expect("invalid brightness");
-    Box::into_raw(Box::new(SPCommand(servicepoint::Command::Brightness(
+    let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::Brightness(
         brightness,
-    ))))
+    ))));
+    assert!(!result.is_null());
+    result
 }
 
 /// Set the brightness of individual tiles in a rectangular area of the display.
 ///
 /// The passed [SPBrightnessGrid] gets consumed.
 ///
-/// Returns: a new `Command::CharBrightness` instance. Will never return NULL.
+/// Returns: a new [Command::CharBrightness] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `grid` is NULL
 ///
 /// # Safety
 ///
@@ -174,11 +199,14 @@ pub unsafe extern "C" fn sp_command_char_brightness(
     y: usize,
     grid: *mut SPBrightnessGrid,
 ) -> *mut SPCommand {
+    assert!(!grid.is_null());
     let byte_grid = *Box::from_raw(grid);
-    Box::into_raw(Box::new(SPCommand(servicepoint::Command::CharBrightness(
+    let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::CharBrightness(
         Origin::new(x, y),
         byte_grid.0,
-    ))))
+    ))));
+    assert!(!result.is_null());
+    result
 }
 
 /// Set pixel data starting at the pixel offset on screen.
@@ -190,7 +218,12 @@ pub unsafe extern "C" fn sp_command_char_brightness(
 ///
 /// The passed [SPBitVec] gets consumed.
 ///
-/// Returns: a new `Command::BitmapLinear` instance. Will never return NULL.
+/// Returns: a new [Command::BitmapLinear] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `bit_vec` is null
+/// - when `compression_code` is not a valid value
 ///
 /// # Safety
 ///
@@ -207,12 +240,15 @@ pub unsafe extern "C" fn sp_command_bitmap_linear(
     bit_vec: *mut SPBitVec,
     compression: SPCompressionCode,
 ) -> *mut SPCommand {
+    assert!(!bit_vec.is_null());
     let bit_vec = *Box::from_raw(bit_vec);
-    Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinear(
+    let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinear(
         offset,
         bit_vec.into(),
         compression.try_into().expect("invalid compression code"),
-    ))))
+    ))));
+    assert!(!result.is_null());
+    result
 }
 
 /// Set pixel data according to an and-mask starting at the offset.
@@ -224,7 +260,12 @@ pub unsafe extern "C" fn sp_command_bitmap_linear(
 ///
 /// The passed [SPBitVec] gets consumed.
 ///
-/// Returns: a new `Command::BitmapLinearAnd` instance. Will never return NULL.
+/// Returns: a new [Command::BitmapLinearAnd] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `bit_vec` is null
+/// - when `compression_code` is not a valid value
 ///
 /// # Safety
 ///
@@ -241,12 +282,15 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and(
     bit_vec: *mut SPBitVec,
     compression: SPCompressionCode,
 ) -> *mut SPCommand {
+    assert!(!bit_vec.is_null());
     let bit_vec = *Box::from_raw(bit_vec);
-    Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearAnd(
+    let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearAnd(
         offset,
         bit_vec.into(),
         compression.try_into().expect("invalid compression code"),
-    ))))
+    ))));
+    assert!(!result.is_null());
+    result
 }
 
 /// Set pixel data according to an or-mask starting at the offset.
@@ -258,7 +302,12 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and(
 ///
 /// The passed [SPBitVec] gets consumed.
 ///
-/// Returns: a new `Command::BitmapLinearOr` instance. Will never return NULL.
+/// Returns: a new [Command::BitmapLinearOr] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `bit_vec` is null
+/// - when `compression_code` is not a valid value
 ///
 /// # Safety
 ///
@@ -275,12 +324,15 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or(
     bit_vec: *mut SPBitVec,
     compression: SPCompressionCode,
 ) -> *mut SPCommand {
+    assert!(!bit_vec.is_null());
     let bit_vec = *Box::from_raw(bit_vec);
-    Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearOr(
+    let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearOr(
         offset,
         bit_vec.into(),
         compression.try_into().expect("invalid compression code"),
-    ))))
+    ))));
+    assert!(!result.is_null());
+    result
 }
 
 /// Set pixel data according to a xor-mask starting at the offset.
@@ -292,7 +344,12 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or(
 ///
 /// The passed [SPBitVec] gets consumed.
 ///
-/// Returns: a new `Command::BitmapLinearXor` instance. Will never return NULL.
+/// Returns: a new [Command::BitmapLinearXor] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `bit_vec` is null
+/// - when `compression_code` is not a valid value
 ///
 /// # Safety
 ///
@@ -309,30 +366,32 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor(
     bit_vec: *mut SPBitVec,
     compression: SPCompressionCode,
 ) -> *mut SPCommand {
+    assert!(!bit_vec.is_null());
     let bit_vec = *Box::from_raw(bit_vec);
-    Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearXor(
+    let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearXor(
         offset,
         bit_vec.into(),
         compression.try_into().expect("invalid compression code"),
-    ))))
+    ))));
+    assert!(!result.is_null());
+    result
 }
 
 /// Show text on the screen.
 ///
-/// <div class="warning">
+/// The passed [SPCp437Grid] gets consumed.
-///     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>
 ///
-/// The passed `SPCp437Grid` gets consumed.///
+/// Returns: a new [Command::Cp437Data] instance. Will never return NULL.
 ///
-/// Returns: a new `Command::Cp437Data` instance. Will never return NULL.
+/// # Panics
+///
+/// - when `grid` is null
 ///
 /// # Safety
 ///
 /// The caller has to make sure that:
 ///
-/// - `grid` points to a valid instance of `SPCp437Grid`
+/// - `grid` points to a valid instance of [SPCp437Grid]
 /// - `grid` is not used concurrently or after this call
 /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
 ///   by explicitly calling `sp_command_free`.
@@ -342,24 +401,32 @@ pub unsafe extern "C" fn sp_command_cp437_data(
     y: usize,
     grid: *mut SPCp437Grid,
 ) -> *mut SPCommand {
+    assert!(!grid.is_null());
     let grid = *Box::from_raw(grid);
-    Box::into_raw(Box::new(SPCommand(servicepoint::Command::Cp437Data(
+    let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::Cp437Data(
         Origin::new(x, y),
         grid.0,
-    ))))
+    ))));
+    assert!(!result.is_null());
+    result
 }
 
 /// Sets a window of pixels to the specified values.
 ///
-/// The passed `SPPixelGrid` gets consumed.
+/// The passed [SPPixelGrid] gets consumed.
 ///
-/// Returns: a new `Command::BitmapLinearWin` instance. Will never return NULL.
+/// Returns: a new [Command::BitmapLinearWin] instance. Will never return NULL.
+///
+/// # Panics
+///
+/// - when `pixel_grid` is null
+/// - when `compression_code` is not a valid value
 ///
 /// # Safety
 ///
 /// The caller has to make sure that:
 ///
-/// - `pixel_grid` points to a valid instance of `SPPixelGrid`
+/// - `pixel_grid` points to a valid instance of [SPPixelGrid]
 /// - `pixel_grid` is not used concurrently or after this call
 /// - `compression` matches one of the allowed enum values
 /// - the returned [SPCommand] instance is freed in some way, either by using a consuming function or
@@ -371,14 +438,17 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win(
     pixel_grid: *mut SPPixelGrid,
     compression_code: SPCompressionCode,
 ) -> *mut SPCommand {
+    assert!(!pixel_grid.is_null());
     let byte_grid = (*Box::from_raw(pixel_grid)).0;
-    Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearWin(
+    let result = Box::into_raw(Box::new(SPCommand(servicepoint::Command::BitmapLinearWin(
         Origin::new(x, y),
         byte_grid,
         compression_code
             .try_into()
             .expect("invalid compression code"),
-    ))))
+    ))));
+    assert!(!result.is_null());
+    result
 }
 
 /// Deallocates a [SPCommand].
@@ -390,14 +460,19 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win(
 /// sp_command_free(c);
 /// ```
 ///
+/// # Panics
+///
+/// - when `command` is NULL
+///
 /// # Safety
 ///
 /// The caller has to make sure that:
 ///
 /// - `command` points to a valid [SPCommand]
 /// - `command` is not used concurrently or after this call
-/// - `command` was not passed to another consuming function, e.g. to create a `SPPacket`
+/// - `command` was not passed to another consuming function, e.g. to create a [SPPacket]
 #[no_mangle]
 pub unsafe extern "C" fn sp_command_free(command: *mut SPCommand) {
+    assert!(!command.is_null());
     _ = Box::from_raw(command);
 }

crates/servicepoint_binding_c/src/connection.rs

@@ -18,7 +18,7 @@ use crate::{SPCommand, SPPacket};
 /// ```
 pub struct SPConnection(pub(crate) servicepoint::Connection);
 
-/// Creates a new instance of `SPConnection`.
+/// Creates a new instance of [SPConnection].
 ///
 /// returns: NULL if connection fails, or connected instance
 ///
@@ -45,7 +45,7 @@ pub unsafe extern "C" fn sp_connection_open(
     Box::into_raw(Box::new(SPConnection(connection)))
 }
 
-/// Sends a `SPPacket` to the display using the `SPConnection`.
+/// Sends a [SPPacket] to the display using the [SPConnection].
 ///
 /// The passed `packet` gets consumed.
 ///
@@ -55,8 +55,8 @@ pub unsafe extern "C" fn sp_connection_open(
 ///
 /// The caller has to make sure that:
 ///
-/// - `connection` points to a valid instance of `SPConnection`
+/// - `connection` points to a valid instance of [SPConnection]
-/// - `packet` points to a valid instance of `SPPacket`
+/// - `packet` points to a valid instance of [SPPacket]
 /// - `packet` is not used concurrently or after this call
 #[no_mangle]
 pub unsafe extern "C" fn sp_connection_send_packet(
@@ -77,8 +77,8 @@ pub unsafe extern "C" fn sp_connection_send_packet(
 ///
 /// The caller has to make sure that:
 ///
-/// - `connection` points to a valid instance of `SPConnection`
+/// - `connection` points to a valid instance of [SPConnection]
-/// - `command` points to a valid instance of `SPPacket`
+/// - `command` points to a valid instance of [SPPacket]
 /// - `command` is not used concurrently or after this call
 #[no_mangle]
 pub unsafe extern "C" fn sp_connection_send_command(
@@ -89,13 +89,19 @@ pub unsafe extern "C" fn sp_connection_send_command(
     (*connection).0.send(command).is_ok()
 }
 
-/// Closes and deallocates a `SPConnection`.
+/// Closes and deallocates a [SPConnection].
+///
+/// # Panics
+///
+/// # Panics
+///
+/// - when `connection` is NULL
 ///
 /// # Safety
 ///
 /// The caller has to make sure that:
 ///
-/// - `connection` points to a valid `SPConnection`
+/// - `connection` points to a valid [SPConnection]
 /// - `connection` is not used concurrently or after this call
 #[no_mangle]
 pub unsafe extern "C" fn sp_connection_free(connection: *mut SPConnection) {

crates/servicepoint_binding_c/src/cp437_grid.rs

@@ -1,4 +1,4 @@
-//! C functions for interacting with `SPCp437Grid`s
+//! C functions for interacting with [SPCp437Grid]s
 //!
 //! prefix `sp_cp437_grid_`
 
@@ -25,9 +25,9 @@ impl Clone for SPCp437Grid {
     }
 }
 
-/// Creates a new `SPCp437Grid` with the specified dimensions.
+/// Creates a new [SPCp437Grid] with the specified dimensions.
 ///
-/// returns: `SPCp437Grid` initialized to 0.
+/// returns: [SPCp437Grid] initialized to 0.
 ///
 /// # Safety
 ///
@@ -45,7 +45,7 @@ pub unsafe extern "C" fn sp_cp437_grid_new(
     ))))
 }
 
-/// Loads a `SPCp437Grid` with the specified dimensions from the provided data.
+/// Loads a [SPCp437Grid] with the specified dimensions from the provided data.
 ///
 /// Will never return NULL.
 ///
@@ -74,7 +74,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load(
     ))))
 }
 
-/// Clones a `SPCp437Grid`.
+/// Clones a [SPCp437Grid].
 ///
 /// Will never return NULL.
 ///
@@ -82,7 +82,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load(
 ///
 /// The caller has to make sure that:
 ///
-/// - `cp437_grid` points to a valid `SPCp437Grid`
+/// - `cp437_grid` points to a valid [SPCp437Grid]
 /// - `cp437_grid` is not written to concurrently
 /// - the returned instance is freed in some way, either by using a consuming function or
 ///   by explicitly calling `sp_cp437_grid_free`.
@@ -93,13 +93,13 @@ pub unsafe extern "C" fn sp_cp437_grid_clone(
     Box::into_raw(Box::new((*cp437_grid).clone()))
 }
 
-/// Deallocates a `SPCp437Grid`.
+/// Deallocates a [SPCp437Grid].
 ///
 /// # Safety
 ///
 /// The caller has to make sure that:
 ///
-/// - `cp437_grid` points to a valid `SPCp437Grid`
+/// - `cp437_grid` points to a valid [SPCp437Grid]
 /// - `cp437_grid` is not used concurrently or after cp437_grid call
 /// - `cp437_grid` was not passed to another consuming function, e.g. to create a [SPCommand]
 #[no_mangle]
@@ -122,7 +122,7 @@ pub unsafe extern "C" fn sp_cp437_grid_free(cp437_grid: *mut SPCp437Grid) {
 ///
 /// The caller has to make sure that:
 ///
-/// - `cp437_grid` points to a valid `SPCp437Grid`
+/// - `cp437_grid` points to a valid [SPCp437Grid]
 /// - `cp437_grid` is not written to concurrently
 #[no_mangle]
 pub unsafe extern "C" fn sp_cp437_grid_get(
@@ -133,7 +133,7 @@ pub unsafe extern "C" fn sp_cp437_grid_get(
     (*cp437_grid).0.get(x, y)
 }
 
-/// Sets the value of the specified position in the `SPCp437Grid`.
+/// Sets the value of the specified position in the [SPCp437Grid].
 ///
 /// # Arguments
 ///
@@ -163,7 +163,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set(
     (*cp437_grid).0.set(x, y, value);
 }
 
-/// Sets the value of all cells in the `SPCp437Grid`.
+/// Sets the value of all cells in the [SPCp437Grid].
 ///
 /// # Arguments
 ///
@@ -174,7 +174,7 @@ pub unsafe extern "C" fn sp_cp437_grid_set(
 ///
 /// The caller has to make sure that:
 ///
-/// - `cp437_grid` points to a valid `SPCp437Grid`
+/// - `cp437_grid` points to a valid [SPCp437Grid]
 /// - `cp437_grid` is not written to or read from concurrently
 #[no_mangle]
 pub unsafe extern "C" fn sp_cp437_grid_fill(
@@ -184,7 +184,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill(
     (*cp437_grid).0.fill(value);
 }
 
-/// Gets the width of the `SPCp437Grid` instance.
+/// Gets the width of the [SPCp437Grid] instance.
 ///
 /// # Arguments
 ///
@@ -194,7 +194,7 @@ pub unsafe extern "C" fn sp_cp437_grid_fill(
 ///
 /// The caller has to make sure that:
 ///
-/// - `cp437_grid` points to a valid `SPCp437Grid`
+/// - `cp437_grid` points to a valid [SPCp437Grid]
 #[no_mangle]
 pub unsafe extern "C" fn sp_cp437_grid_width(
     cp437_grid: *const SPCp437Grid,
@@ -202,7 +202,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width(
     (*cp437_grid).0.width()
 }
 
-/// Gets the height of the `SPCp437Grid` instance.
+/// Gets the height of the [SPCp437Grid] instance.
 ///
 /// # Arguments
 ///
@@ -212,7 +212,7 @@ pub unsafe extern "C" fn sp_cp437_grid_width(
 ///
 /// The caller has to make sure that:
 ///
-/// - `cp437_grid` points to a valid `SPCp437Grid`
+/// - `cp437_grid` points to a valid [SPCp437Grid]
 #[no_mangle]
 pub unsafe extern "C" fn sp_cp437_grid_height(
     cp437_grid: *const SPCp437Grid,
@@ -220,7 +220,7 @@ pub unsafe extern "C" fn sp_cp437_grid_height(
     (*cp437_grid).0.height()
 }
 
-/// Gets an unsafe reference to the data of the `SPCp437Grid` instance.
+/// Gets an unsafe reference to the data of the [SPCp437Grid] instance.
 ///
 /// Will never return NULL.
 ///
@@ -228,9 +228,9 @@ pub unsafe extern "C" fn sp_cp437_grid_height(
 ///
 /// The caller has to make sure that:
 ///
-/// - `cp437_grid` points to a valid `SPCp437Grid`
+/// - `cp437_grid` points to a valid [SPCp437Grid]
-/// - the returned memory range is never accessed after the passed `SPCp437Grid` has been freed
+/// - the returned memory range is never accessed after the passed [SPCp437Grid] has been freed
-/// - the returned memory range is never accessed concurrently, either via the `SPCp437Grid` or directly
+/// - the returned memory range is never accessed concurrently, either via the [SPCp437Grid] or directly
 #[no_mangle]
 pub unsafe extern "C" fn sp_cp437_grid_unsafe_data_ref(
     cp437_grid: *mut SPCp437Grid,

crates/servicepoint_binding_c/src/packet.rs

@@ -1,4 +1,4 @@
-//! C functions for interacting with `SPPacket`s
+//! C functions for interacting with [SPPacket]s
 //!
 //! prefix `sp_packet_`
 
@@ -9,7 +9,7 @@ use crate::SPCommand;
 /// The raw packet
 pub struct SPPacket(pub(crate) servicepoint::packet::Packet);
 
-/// Turns a [SPCommand] into a `SPPacket`.
+/// Turns a [SPCommand] into a [SPPacket].
 /// The [SPCommand] gets consumed.
 ///
 /// Will never return NULL.
@@ -20,7 +20,7 @@ pub struct SPPacket(pub(crate) servicepoint::packet::Packet);
 ///
 /// - [SPCommand] points to a valid instance of [SPCommand]
 /// - [SPCommand] is not used concurrently or after this call
-/// - the returned `SPPacket` instance is freed in some way, either by using a consuming function or
+/// - the returned [SPPacket] instance is freed in some way, either by using a consuming function or
 ///   by explicitly calling `sp_packet_free`.
 #[no_mangle]
 pub unsafe extern "C" fn sp_packet_from_command(
@@ -31,7 +31,7 @@ pub unsafe extern "C" fn sp_packet_from_command(
     Box::into_raw(Box::new(packet))
 }
 
-/// Tries to load a `SPPacket` from the passed array with the specified length.
+/// Tries to load a [SPPacket] from the passed array with the specified length.
 ///
 /// returns: NULL in case of an error, pointer to the allocated packet otherwise
 ///
@@ -41,7 +41,7 @@ pub unsafe extern "C" fn sp_packet_from_command(
 ///
 /// - `data` points to a valid memory region of at least `length` bytes
 /// - `data` is not written to concurrently
-/// - the returned `SPPacket` instance is freed in some way, either by using a consuming function or
+/// - the returned [SPPacket] instance is freed in some way, either by using a consuming function or
 ///   by explicitly calling `sp_packet_free`.
 #[no_mangle]
 pub unsafe extern "C" fn sp_packet_try_load(
@@ -55,7 +55,7 @@ pub unsafe extern "C" fn sp_packet_try_load(
     }
 }
 
-/// Clones a `SPPacket`.
+/// Clones a [SPPacket].
 ///
 /// Will never return NULL.
 ///
@@ -63,7 +63,7 @@ pub unsafe extern "C" fn sp_packet_try_load(
 ///
 /// The caller has to make sure that:
 ///
-/// - `packet` points to a valid `SPPacket`
+/// - `packet` points to a valid [SPPacket]
 /// - `packet` is not written to concurrently
 /// - the returned instance is freed in some way, either by using a consuming function or
 ///   by explicitly calling `sp_packet_free`.
@@ -74,13 +74,13 @@ pub unsafe extern "C" fn sp_packet_clone(
     Box::into_raw(Box::new(SPPacket((*packet).0.clone())))
 }
 
-/// Deallocates a `SPPacket`.
+/// Deallocates a [SPPacket].
 ///
 /// # Safety
 ///
 /// The caller has to make sure that:
 ///
-/// - `packet` points to a valid `SPPacket`
+/// - `packet` points to a valid [SPPacket]
 /// - `packet` is not used concurrently or after this call
 #[no_mangle]
 pub unsafe extern "C" fn sp_packet_free(packet: *mut SPPacket) {

crates/servicepoint_binding_c/src/pixel_grid.rs

@@ -1,4 +1,4 @@
-//! C functions for interacting with `SPPixelGrid`s
+//! C functions for interacting with [SPPixelGrid]s
 //!
 //! prefix `sp_pixel_grid_`
 
@@ -18,14 +18,14 @@ use crate::byte_slice::SPByteSlice;
 /// ```
 pub struct SPPixelGrid(pub(crate) servicepoint::PixelGrid);
 
-/// Creates a new `SPPixelGrid` with the specified dimensions.
+/// Creates a new [SPPixelGrid] with the specified dimensions.
 ///
 /// # Arguments
 ///
 /// - `width`: size in pixels in x-direction
 /// - `height`: size in pixels in y-direction
 ///
-/// returns: `SPPixelGrid` initialized to all pixels off. Will never return NULL.
+/// returns: [SPPixelGrid] initialized to all pixels off. Will never return NULL.
 ///
 /// # Panics
 ///
@@ -47,14 +47,14 @@ pub unsafe extern "C" fn sp_pixel_grid_new(
     ))))
 }
 
-/// Loads a `SPPixelGrid` with the specified dimensions from the provided data.
+/// Loads a [SPPixelGrid] with the specified dimensions from the provided data.
 ///
 /// # Arguments
 ///
 /// - `width`: size in pixels in x-direction
 /// - `height`: size in pixels in y-direction
 ///
-/// returns: `SPPixelGrid` that contains a copy of the provided data. Will never return NULL.
+/// returns: [SPPixelGrid] that contains a copy of the provided data. Will never return NULL.
 ///
 /// # Panics
 ///
@@ -81,7 +81,7 @@ pub unsafe extern "C" fn sp_pixel_grid_load(
     ))))
 }
 
-/// Clones a `SPPixelGrid`.
+/// Clones a [SPPixelGrid].
 ///
 /// Will never return NULL.
 ///
@@ -89,7 +89,7 @@ pub unsafe extern "C" fn sp_pixel_grid_load(
 ///
 /// The caller has to make sure that:
 ///
-/// - `pixel_grid` points to a valid `SPPixelGrid`
+/// - `pixel_grid` points to a valid [SPPixelGrid]
 /// - `pixel_grid` is not written to concurrently
 /// - the returned instance is freed in some way, either by using a consuming function or
 ///   by explicitly calling `sp_pixel_grid_free`.
@@ -100,13 +100,13 @@ pub unsafe extern "C" fn sp_pixel_grid_clone(
     Box::into_raw(Box::new(SPPixelGrid((*pixel_grid).0.clone())))
 }
 
-/// Deallocates a `SPPixelGrid`.
+/// Deallocates a [SPPixelGrid].
 ///
 /// # Safety
 ///
 /// The caller has to make sure that:
 ///
-/// - `pixel_grid` points to a valid `SPPixelGrid`
+/// - `pixel_grid` points to a valid [SPPixelGrid]
 /// - `pixel_grid` is not used concurrently or after pixel_grid call
 /// - `pixel_grid` was not passed to another consuming function, e.g. to create a [SPCommand]
 #[no_mangle]
@@ -114,7 +114,7 @@ pub unsafe extern "C" fn sp_pixel_grid_free(pixel_grid: *mut SPPixelGrid) {
     _ = Box::from_raw(pixel_grid);
 }
 
-/// Gets the current value at the specified position in the `SPPixelGrid`.
+/// Gets the current value at the specified position in the [SPPixelGrid].
 ///
 /// # Arguments
 ///
@@ -129,7 +129,7 @@ pub unsafe extern "C" fn sp_pixel_grid_free(pixel_grid: *mut SPPixelGrid) {
 ///
 /// The caller has to make sure that:
 ///
-/// - `pixel_grid` points to a valid `SPPixelGrid`
+/// - `pixel_grid` points to a valid [SPPixelGrid]
 /// - `pixel_grid` is not written to concurrently
 #[no_mangle]
 pub unsafe extern "C" fn sp_pixel_grid_get(
@@ -140,7 +140,7 @@ pub unsafe extern "C" fn sp_pixel_grid_get(
     (*pixel_grid).0.get(x, y)
 }
 
-/// Sets the value of the specified position in the `SPPixelGrid`.
+/// Sets the value of the specified position in the [SPPixelGrid].
 ///
 /// # Arguments
 ///
@@ -158,7 +158,7 @@ pub unsafe extern "C" fn sp_pixel_grid_get(
 ///
 /// The caller has to make sure that:
 ///
-/// - `pixel_grid` points to a valid `SPPixelGrid`
+/// - `pixel_grid` points to a valid [SPPixelGrid]
 /// - `pixel_grid` is not written to or read from concurrently
 #[no_mangle]
 pub unsafe extern "C" fn sp_pixel_grid_set(
@@ -170,7 +170,7 @@ pub unsafe extern "C" fn sp_pixel_grid_set(
     (*pixel_grid).0.set(x, y, value);
 }
 
-/// Sets the state of all pixels in the `SPPixelGrid`.
+/// Sets the state of all pixels in the [SPPixelGrid].
 ///
 /// # Arguments
 ///
@@ -181,7 +181,7 @@ pub unsafe extern "C" fn sp_pixel_grid_set(
 ///
 /// The caller has to make sure that:
 ///
-/// - `pixel_grid` points to a valid `SPPixelGrid`
+/// - `pixel_grid` points to a valid [SPPixelGrid]
 /// - `pixel_grid` is not written to or read from concurrently
 #[no_mangle]
 pub unsafe extern "C" fn sp_pixel_grid_fill(
@@ -191,7 +191,7 @@ pub unsafe extern "C" fn sp_pixel_grid_fill(
     (*pixel_grid).0.fill(value);
 }
 
-/// Gets the width in pixels of the `SPPixelGrid` instance.
+/// Gets the width in pixels of the [SPPixelGrid] instance.
 ///
 /// # Arguments
 ///
@@ -201,7 +201,7 @@ pub unsafe extern "C" fn sp_pixel_grid_fill(
 ///
 /// The caller has to make sure that:
 ///
-/// - `pixel_grid` points to a valid `SPPixelGrid`
+/// - `pixel_grid` points to a valid [SPPixelGrid]
 #[no_mangle]
 pub unsafe extern "C" fn sp_pixel_grid_width(
     pixel_grid: *const SPPixelGrid,
@@ -209,7 +209,7 @@ pub unsafe extern "C" fn sp_pixel_grid_width(
     (*pixel_grid).0.width()
 }
 
-/// Gets the height in pixels of the `SPPixelGrid` instance.
+/// Gets the height in pixels of the [SPPixelGrid] instance.
 ///
 /// # Arguments
 ///
@@ -219,7 +219,7 @@ pub unsafe extern "C" fn sp_pixel_grid_width(
 ///
 /// The caller has to make sure that:
 ///
-/// - `pixel_grid` points to a valid `SPPixelGrid`
+/// - `pixel_grid` points to a valid [SPPixelGrid]
 #[no_mangle]
 pub unsafe extern "C" fn sp_pixel_grid_height(
     pixel_grid: *const SPPixelGrid,
@@ -227,15 +227,15 @@ pub unsafe extern "C" fn sp_pixel_grid_height(
     (*pixel_grid).0.height()
 }
 
-/// Gets an unsafe reference to the data of the `SPPixelGrid` instance.
+/// Gets an unsafe reference to the data of the [SPPixelGrid] instance.
 ///
 /// ## Safety
 ///
 /// The caller has to make sure that:
 ///
-/// - `pixel_grid` points to a valid `SPPixelGrid`
+/// - `pixel_grid` points to a valid [SPPixelGrid]
-/// - the returned memory range is never accessed after the passed `SPPixelGrid` has been freed
+/// - the returned memory range is never accessed after the passed [SPPixelGrid] has been freed
-/// - the returned memory range is never accessed concurrently, either via the `SPPixelGrid` or directly
+/// - the returned memory range is never accessed concurrently, either via the [SPPixelGrid] or directly
 #[no_mangle]
 pub unsafe extern "C" fn sp_pixel_grid_unsafe_data_ref(
     pixel_grid: *mut SPPixelGrid,