copy paste command docs

crates/servicepoint_binding_c/src/command.rs

@@ -18,7 +18,7 @@ use crate::SPOffset;
 ///
 /// This struct and associated functions implement the UDP protocol for the display.
 ///
-/// To send a `CCommand`, use a `CConnection`.
+/// To send a `SPCommand`, use a `SPConnection`.
 ///
 /// # Examples
 ///
@@ -34,18 +34,18 @@ impl Clone for SPCommand {
     }
 }
 
-/// Tries to turn a `Packet` into a `Command`. The packet is deallocated in the process.
+/// Tries to turn a `SPPacket` into a `SPCommand`. The packet is deallocated in the process.
 ///
-/// Returns: pointer to new `Command` instance or NULL
+/// Returns: pointer to new `SPCommand` instance or NULL
 ///
 /// # Safety
 ///
 /// The caller has to make sure that:
 ///
-/// - `packet` points to a valid instance of `Packet`
+/// - `packet` points to a valid instance of `SPPacket`
 /// - `packet` is not used concurrently or after this call
 /// - the result is checked for NULL
-/// - the returned `Command` instance is freed in some way, either by using a consuming function or
+/// - the returned `SPCommand` instance is freed in some way, either by using a consuming function or
 ///   by explicitly calling `sp_command_dealloc`.
 #[no_mangle]
 pub unsafe extern "C" fn sp_command_try_from_packet(
@@ -58,7 +58,7 @@ pub unsafe extern "C" fn sp_command_try_from_packet(
     }
 }
 
-/// Clones a `Command` instance.
+/// Clones a `SPCommand` instance.
 ///
 /// # Safety
 ///
@@ -77,6 +77,14 @@ pub unsafe extern "C" fn sp_command_clone(
 
 /// Allocates a new `Command::Clear` instance.
 ///
+/// Set all pixels to the off state. Does not affect brightness.
+///
+/// # Examples
+///
+/// ```C
+/// sp_connection_send(connection, sp_command_clear());
+/// ```
+///
 /// # Safety
 ///
 /// The caller has to make sure that:
@@ -90,6 +98,9 @@ pub unsafe extern "C" fn sp_command_clear() -> *mut SPCommand {
 
 /// Allocates a new `Command::HardReset` instance.
 ///
+/// Kills the udp daemon on the display, which usually results in a restart.
+/// Please do not send this in your normal program flow.
+///
 /// # Safety
 ///
 /// The caller has to make sure that:
@@ -141,6 +152,8 @@ pub unsafe extern "C" fn sp_command_brightness(
 /// Allocates a new `Command::CharBrightness` instance.
 /// The passed `SPBrightnessGrid` gets consumed.
 ///
+/// Set the brightness of individual tiles in a rectangular area of the display.
+///
 /// # Safety
 ///
 /// The caller has to make sure that:
@@ -165,6 +178,13 @@ pub unsafe extern "C" fn sp_command_char_brightness(
 /// Allocates a new `Command::BitmapLinear` instance.
 /// The passed `BitVec` gets consumed.
 ///
+/// Set pixel data starting at the pixel offset on screen.
+///
+/// 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.
+///
 /// # Safety
 ///
 /// The caller has to make sure that:
@@ -191,6 +211,13 @@ pub unsafe extern "C" fn sp_command_bitmap_linear(
 /// Allocates a new `Command::BitmapLinearAnd` instance.
 /// The passed `BitVec` gets consumed.
 ///
+/// Set pixel data according to an and-mask starting at the offset.
+///
+/// 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.
+///
 /// # Safety
 ///
 /// The caller has to make sure that:
@@ -217,6 +244,13 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and(
 /// Allocates a new `Command::BitmapLinearOr` instance.
 /// The passed `BitVec` gets consumed.
 ///
+/// Set pixel data according to an or-mask starting at the offset.
+///
+/// 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.
+///
 /// # Safety
 ///
 /// The caller has to make sure that:
@@ -243,6 +277,13 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or(
 /// Allocates a new `Command::BitmapLinearXor` instance.
 /// The passed `BitVec` gets consumed.
 ///
+/// Set pixel data according to a xor-mask starting at the offset.
+///
+/// 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.
+///
 /// # Safety
 ///
 /// The caller has to make sure that:
@@ -269,6 +310,13 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor(
 /// Allocates a new `Command::Cp437Data` instance.
 /// The passed `ByteGrid` gets consumed.
 ///
+/// Show text on the screen.
+///
+/// <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.
+/// </div>
+///
 /// # Safety
 ///
 /// The caller has to make sure that:
@@ -293,6 +341,8 @@ pub unsafe extern "C" fn sp_command_cp437_data(
 /// Allocates a new `Command::BitmapLinearWin` instance.
 /// The passed `PixelGrid` gets consumed.
 ///
+/// Sets a window of pixels to the specified values
+///
 /// # Safety
 ///
 /// The caller has to make sure that:
@@ -321,6 +371,13 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_win(
 
 /// Deallocates a `Command`.
 ///
+/// # Examples
+///
+/// ```C
+/// SPCommand c = sp_command_clear();
+/// sp_command_dealloc(c);
+/// ```
+///
 /// # Safety
 ///
 /// The caller has to make sure that: