add more documentation, add doc lint

crates/servicepoint_binding_c/src/bit_vec.rs

@@ -5,13 +5,28 @@ use crate::c_slice::CByteSlice;
 
 /// Creates a new `BitVec` instance.
 /// The returned instance has to be freed with `bit_vec_dealloc`.
+///
+/// # Safety
+///
+/// The caller has to make sure that:7
+///
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_bit_vec_dealloc`.
 #[no_mangle]
 pub unsafe extern "C" fn sp_bit_vec_new(size: usize) -> *mut BitVec {
     Box::into_raw(Box::new(BitVec::new(size)))
 }
 
 /// Loads a `BitVec` from the provided data.
-/// The returned instance has to be freed with `bit_vec_dealloc`.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `data` points to a valid memory location of at least `data_length`
+///   bytes in size.
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_bit_vec_dealloc`.
 #[no_mangle]
 pub unsafe extern "C" fn sp_bit_vec_load(
     data: *const u8,
@@ -22,7 +37,15 @@ pub unsafe extern "C" fn sp_bit_vec_load(
 }
 
 /// Clones a `BitVec`.
-/// The returned instance has to be freed with `bit_vec_dealloc`.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `this` points to a valid `BitVec`
+/// - `this` is not written to concurrently
+/// - the returned instance is freed in some way, either by using a consuming function or
+///   by explicitly calling `sp_bit_vec_dealloc`.
 #[no_mangle]
 pub unsafe extern "C" fn sp_bit_vec_clone(this: *const BitVec) -> *mut BitVec {
     Box::into_raw(Box::new((*this).clone()))
@@ -30,13 +53,26 @@ pub unsafe extern "C" fn sp_bit_vec_clone(this: *const BitVec) -> *mut BitVec {
 
 /// Deallocates a `BitVec`.
 ///
-/// Note: do not call this if the grid has been consumed in another way, e.g. to create a command.
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `this` points to a valid `BitVec`
+/// - `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_bit_vec_dealloc(this: *mut BitVec) {
     _ = Box::from_raw(this);
 }
 
 /// Gets the value of a bit from the `BitVec`.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `this` points to a valid `BitVec`
+/// - `this` is not written to concurrently
 #[no_mangle]
 pub unsafe extern "C" fn sp_bit_vec_get(
     this: *const BitVec,
@@ -46,6 +82,13 @@ pub unsafe extern "C" fn sp_bit_vec_get(
 }
 
 /// Sets the value of a bit in the `BitVec`.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `this` points to a valid `BitVec`
+/// - `this` is not written to or read from concurrently
 #[no_mangle]
 pub unsafe extern "C" fn sp_bit_vec_set(
     this: *mut BitVec,
@@ -56,18 +99,37 @@ pub unsafe extern "C" fn sp_bit_vec_set(
 }
 
 /// Sets the value of all bits in the `BitVec`.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `this` points to a valid `BitVec`
+/// - `this` is not written to or read from concurrently
 #[no_mangle]
 pub unsafe extern "C" fn sp_bit_vec_fill(this: *mut BitVec, value: bool) {
     (*this).fill(value)
 }
 
 /// Gets the length of the `BitVec` in bits.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `this` points to a valid `BitVec`
 #[no_mangle]
 pub unsafe extern "C" fn sp_bit_vec_len(this: *const BitVec) -> usize {
     (*this).len()
 }
 
 /// Returns true if length is 0.
+///
+/// # Safety
+///
+/// The caller has to make sure that:
+///
+/// - `this` points to a valid `BitVec`
 #[no_mangle]
 pub unsafe extern "C" fn sp_bit_vec_is_empty(this: *const BitVec) -> bool {
     (*this).is_empty()
@@ -77,11 +139,11 @@ pub unsafe extern "C" fn sp_bit_vec_is_empty(this: *const BitVec) -> bool {
 ///
 /// ## Safety
 ///
-/// The caller has to make sure to never access the returned memory after the `BitVec`
-/// instance has been consumed or manually deallocated.
+/// The caller has to make sure that:
 ///
-/// Reading and writing concurrently to either the original instance or the returned data will
-/// result in undefined behavior.
+/// - `this` points to a valid `BitVec`
+/// - the returned memory range is never accessed after the passed `BitVec` has been freed
+/// - the returned memory range is never accessed concurrently, either via the `BitVec` or directly
 #[no_mangle]
 pub unsafe extern "C" fn sp_bit_vec_unsafe_data_ref(
     this: *mut BitVec,

crates/servicepoint_binding_c/src/lib.rs

@@ -1,14 +1,41 @@
+//! C API wrapper for the `servicepoint` crate.
+
 pub use servicepoint::{
     CompressionCode, PIXEL_COUNT, PIXEL_HEIGHT, PIXEL_WIDTH, TILE_HEIGHT,
     TILE_SIZE, TILE_WIDTH,
 };
 
+/// C functions for interacting with `BitVec`s
 pub mod bit_vec;
+
+/// C functions for interacting with `ByteGrid`s
 pub mod byte_grid;
+
+/// C functions for interacting with `BitVec`s
 pub mod c_slice;
+
+/// C functions for interacting with `Command`s
 pub mod command;
+
+/// C functions for interacting with `Connection`s
 pub mod connection;
+
+/// C functions for interacting with `Packet`s
 pub mod packet;
+
+/// C functions for interacting with `PixelGrid`s
 pub mod pixel_grid;
 
+/// The minimum time needed for the display to refresh the screen in ms.
 pub const FRAME_PACING_MS: u32 = servicepoint::FRAME_PACING.as_millis() as u32;
+
+#[repr(C)]
+/// Represents a span of memory (`&mut [u8]` ) as a struct usable by C code.
+///
+/// Usage of this type is inherently unsafe.
+pub struct CByteSlice {
+    /// The start address of the memory
+    pub start: *mut u8,
+    /// The amount of memory in bytes
+    pub length: usize,
+}