named fields instead of tuple for Packet, doc adjustments

crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h

@@ -105,7 +105,7 @@ typedef struct SPBrightnessGrid SPBrightnessGrid;
  *
  * 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
  *
@@ -539,6 +539,13 @@ size_t sp_brightness_grid_width(const struct SPBrightnessGrid *this_);
  * 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:
@@ -557,6 +564,13 @@ struct SPCommand *sp_command_bitmap_linear(SPOffset offset,
  * 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:
@@ -575,6 +589,13 @@ struct SPCommand *sp_command_bitmap_linear_and(SPOffset offset,
  * 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:
@@ -593,6 +614,8 @@ struct SPCommand *sp_command_bitmap_linear_or(SPOffset offset,
  * 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:
@@ -612,6 +635,13 @@ struct SPCommand *sp_command_bitmap_linear_win(size_t x,
  * 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:
@@ -647,6 +677,8 @@ struct SPCommand *sp_command_brightness(uint8_t 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:
@@ -663,6 +695,14 @@ struct SPCommand *sp_command_char_brightness(size_t x,
 /**
  * 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:
@@ -673,7 +713,7 @@ struct SPCommand *sp_command_char_brightness(size_t x,
 struct SPCommand *sp_command_clear(void);
 
 /**
- * Clones a `Command` instance.
+ * Clones a `SPCommand` instance.
  *
  * # Safety
  *
@@ -690,6 +730,13 @@ struct SPCommand *sp_command_clone(const struct SPCommand *original);
  * 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:
@@ -706,6 +753,13 @@ struct SPCommand *sp_command_cp437_data(size_t x,
 /**
  * Deallocates a `Command`.
  *
+ * # Examples
+ *
+ * ```C
+ * SPCommand c = sp_command_clear();
+ * sp_command_dealloc(c);
+ * ```
+ *
  * # Safety
  *
  * The caller has to make sure that:
@@ -731,6 +785,9 @@ struct SPCommand *sp_command_fade_out(void);
 /**
  * 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:
@@ -741,18 +798,18 @@ struct SPCommand *sp_command_fade_out(void);
 struct SPCommand *sp_command_hard_reset(void);
 
 /**
- * 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`.
  */
 struct SPCommand *sp_command_try_from_packet(struct SPPacket *packet);