even more docs

cbindgen.toml

@@ -35,8 +35,8 @@ include = []
 exclude = ["BitVec"]
 
 [export.rename]
-"SpByteSlice" = "ByteSlice"
+"SPCommand" = "Command"
-"SpCommand" = "Command"
+"DisplayBitVec" = "BitVec"
 
 [enum]
 rename_variants = "QualifiedScreamingSnakeCase"

include/servicepoint.h

@@ -125,6 +125,11 @@ enum CommandCode
 typedef uint16_t CommandCode;
 #endif // __cplusplus
 
+/**
+ * Specifies the kind of command struct.
+ *
+ * This is _not_ equivalent to the [servicepoint::CommandCode]s.
+ */
 enum CommandTag
 #ifdef __cplusplus
   : uint8_t
@@ -341,7 +346,7 @@ typedef struct Cp437GridCommand Cp437GridCommand;
 /**
  * This is a type only used by cbindgen to have a type for pointers.
  */
-typedef struct DisplayBitVec DisplayBitVec;
+typedef struct BitVec BitVec;
 
 /**
  * <div class="warning">Untested</div>
@@ -531,6 +536,9 @@ typedef size_t Offset;
  */
 typedef ValueGrid_u8 Cp437Grid;
 
+/**
+ * Pointer to one of the available command structs.
+ */
 typedef union {
     uint8_t *null;
     BitmapCommand */*notnull*/ bitmap;
@@ -545,6 +553,13 @@ typedef union {
     FadeOutCommand */*notnull*/ fade_out;
 } CommandUnion;
 
+/**
+ * This struct represents a pointer to one of the possible command structs.
+ *
+ * Only ever access `data` with the correct data type as specified by `tag`!
+ *
+ * Rust equivalent: [TypedCommand].
+ */
 typedef struct {
     /**
      * Specifies which kind of command struct is contained in `data`
@@ -554,7 +569,7 @@ typedef struct {
      * The pointer to the command struct
      */
     CommandUnion data;
-} SPCommand;
+} Command;
 
 /**
  * A raw header.
@@ -622,7 +637,7 @@ void sp_bitmap_free(Bitmap */*notnull*/ bitmap);
  *
  * Returns NULL in case of error.
  */
-Bitmap *sp_bitmap_from_bitvec(size_t width, DisplayBitVec */*notnull*/ bitvec);
+Bitmap *sp_bitmap_from_bitvec(size_t width, BitVec */*notnull*/ bitvec);
 
 /**
  * Gets the current value at the specified position in the [Bitmap].
@@ -650,7 +665,7 @@ size_t sp_bitmap_height(Bitmap */*notnull*/ bitmap);
 /**
  * Consumes the Bitmap and returns the contained BitVec
  */
-DisplayBitVec */*notnull*/ sp_bitmap_into_bitvec(Bitmap */*notnull*/ bitmap);
+BitVec */*notnull*/ sp_bitmap_into_bitvec(Bitmap */*notnull*/ bitmap);
 
 /**
  * Creates a [BitmapCommand] and immediately turns that into a [Packet].
@@ -754,27 +769,27 @@ ByteSlice sp_bitmap_unsafe_data_ref(Bitmap */*notnull*/ bitmap);
 size_t sp_bitmap_width(Bitmap */*notnull*/ bitmap);
 
 /**
- * Clones a [SPBitVec].
+ * Clones a [DisplayBitVec].
  */
-DisplayBitVec */*notnull*/ sp_bitvec_clone(DisplayBitVec */*notnull*/ bit_vec);
+BitVec */*notnull*/ sp_bitvec_clone(BitVec */*notnull*/ bit_vec);
 
 /**
- * Sets the value of all bits in the [SPBitVec].
+ * Sets the value of all bits in the [DisplayBitVec].
  *
  * # Arguments
  *
  * - `bit_vec`: instance to write to
  * - `value`: the value to set all bits to
  */
-void sp_bitvec_fill(DisplayBitVec */*notnull*/ bit_vec, bool value);
+void sp_bitvec_fill(BitVec */*notnull*/ bit_vec, bool value);
 
 /**
- * Deallocates a [SPBitVec].
+ * Deallocates a [DisplayBitVec].
  */
-void sp_bitvec_free(DisplayBitVec */*notnull*/ bit_vec);
+void sp_bitvec_free(BitVec */*notnull*/ bit_vec);
 
 /**
- * Gets the value of a bit from the [SPBitVec].
+ * Gets the value of a bit from the [DisplayBitVec].
  *
  * # Arguments
  *
@@ -787,16 +802,16 @@ void sp_bitvec_free(DisplayBitVec */*notnull*/ bit_vec);
  *
  * - when accessing `index` out of bounds
  */
-bool sp_bitvec_get(DisplayBitVec */*notnull*/ bit_vec, size_t index);
+bool sp_bitvec_get(BitVec */*notnull*/ bit_vec, size_t index);
 
 /**
  * Creates a [BitVecCommand] and immediately turns that into a [Packet].
  *
- * The provided [SPBitVec] gets consumed.
+ * The provided [DisplayBitVec] gets consumed.
  *
  * Returns NULL in case of an error.
  */
-Packet *sp_bitvec_into_packet(DisplayBitVec */*notnull*/ bitvec,
+Packet *sp_bitvec_into_packet(BitVec */*notnull*/ bitvec,
                               size_t offset,
                               BinaryOperation operation,
                               CompressionCode compression);
@@ -808,41 +823,41 @@ Packet *sp_bitvec_into_packet(DisplayBitVec */*notnull*/ bitvec,
  *
  * - `bit_vec`: instance to write to
  */
-bool sp_bitvec_is_empty(DisplayBitVec */*notnull*/ bit_vec);
+bool sp_bitvec_is_empty(BitVec */*notnull*/ bit_vec);
 
 /**
- * Gets the length of the [SPBitVec] in bits.
+ * Gets the length of the [DisplayBitVec] in bits.
  *
  * # Arguments
  *
  * - `bit_vec`: instance to write to
  */
-size_t sp_bitvec_len(DisplayBitVec */*notnull*/ bit_vec);
+size_t sp_bitvec_len(BitVec */*notnull*/ bit_vec);
 
 /**
- * Interpret the data as a series of bits and load then into a new [SPBitVec] instance.
+ * Interpret the data as a series of bits and load then into a new [DisplayBitVec] instance.
  *
- * returns: [SPBitVec] instance containing data.
+ * returns: [DisplayBitVec] instance containing data.
  */
-DisplayBitVec */*notnull*/ sp_bitvec_load(ByteSlice data);
+BitVec */*notnull*/ sp_bitvec_load(ByteSlice data);
 
 /**
- * Creates a new [SPBitVec] instance.
+ * Creates a new [DisplayBitVec] instance.
  *
  * # Arguments
  *
  * - `size`: size in bits.
  *
- * returns: [SPBitVec] with all bits set to false.
+ * returns: [DisplayBitVec] with all bits set to false.
  *
  * # Panics
  *
  * - when `size` is not divisible by 8.
  */
-DisplayBitVec */*notnull*/ sp_bitvec_new(size_t size);
+BitVec */*notnull*/ sp_bitvec_new(size_t size);
 
 /**
- * Sets the value of a bit in the [SPBitVec].
+ * Sets the value of a bit in the [DisplayBitVec].
  *
  * # Arguments
  *
@@ -854,12 +869,10 @@ DisplayBitVec */*notnull*/ sp_bitvec_new(size_t size);
  *
  * - when accessing `index` out of bounds
  */
-void sp_bitvec_set(DisplayBitVec */*notnull*/ bit_vec,
+void sp_bitvec_set(BitVec */*notnull*/ bit_vec, size_t index, bool value);
-                   size_t index,
-                   bool value);
 
 /**
- * Gets an unsafe reference to the data of the [SPBitVec] instance.
+ * Gets an unsafe reference to the data of the [DisplayBitVec] instance.
  *
  * The returned memory is valid for the lifetime of the bitvec.
  *
@@ -867,7 +880,7 @@ void sp_bitvec_set(DisplayBitVec */*notnull*/ bit_vec,
  *
  * - `bit_vec`: instance to write to
  */
-ByteSlice sp_bitvec_unsafe_data_ref(DisplayBitVec */*notnull*/ bit_vec);
+ByteSlice sp_bitvec_unsafe_data_ref(BitVec */*notnull*/ bit_vec);
 
 /**
  * Clones a [BrightnessGrid].
@@ -1111,15 +1124,23 @@ void sp_char_grid_set(CharGrid */*notnull*/ char_grid,
  */
 size_t sp_char_grid_width(CharGrid */*notnull*/ char_grid);
 
+/**
+ * Clones an [BitmapCommand] instance.
+ *
+ * returns: a new [BitmapCommand] instance.
+ */
 BitmapCommand */*notnull*/ sp_cmd_bitmap_clone(BitmapCommand */*notnull*/ command);
 
+/**
+ * Deallocates a [BitmapCommand] instance.
+ */
 void sp_cmd_bitmap_free(BitmapCommand */*notnull*/ command);
 
 /**
  * Move the provided [Bitmap] into a new [BitmapCommand],
  * leaving other fields as their default values.
  *
- * Rust equivalent: [`<BitmapCommand as From<Bitmap>>::from`]
+ * Rust equivalent: `BitmapCommand::from(bitmap)`
  */
 BitmapCommand */*notnull*/ sp_cmd_bitmap_from_bitmap(Bitmap */*notnull*/ bitmap);
 
@@ -1133,14 +1154,18 @@ BitmapCommand */*notnull*/ sp_cmd_bitmap_from_bitmap(Bitmap */*notnull*/ bitmap)
  */
 Bitmap */*notnull*/ sp_cmd_bitmap_get(BitmapCommand */*notnull*/ command);
 
+/**
+ * Reads the compression kind of the [BitmapCommand].
+ */
 CompressionCode sp_cmd_bitmap_get_compression(BitmapCommand */*notnull*/ command);
 
+/**
+ * Reads the origin field of the [BitmapCommand].
+ */
 void sp_cmd_bitmap_get_origin(BitmapCommand */*notnull*/ command,
                               size_t */*notnull*/ origin_x,
                               size_t */*notnull*/ origin_y);
 
-Packet *sp_cmd_bitmap_into_packet(BitmapCommand */*notnull*/ command);
-
 /**
  * Sets a window of pixels to the specified values.
  *
@@ -1154,32 +1179,63 @@ BitmapCommand */*notnull*/ sp_cmd_bitmap_new(Bitmap */*notnull*/ bitmap,
                                              CompressionCode compression);
 
 /**
- * Moves the provided bitmap to be contained in the command.
+ * Moves the provided [Bitmap] to be contained in the [BitmapCommand].
  */
 void sp_cmd_bitmap_set(BitmapCommand */*notnull*/ command,
                        Bitmap */*notnull*/ bitmap);
 
+/**
+ * Overwrites the compression kind of the [BitmapCommand].
+ */
 void sp_cmd_bitmap_set_compression(BitmapCommand */*notnull*/ command,
                                    CompressionCode compression);
 
+/**
+ * Overwrites the origin field of the [BitmapCommand].
+ */
 void sp_cmd_bitmap_set_origin(BitmapCommand */*notnull*/ command,
                               size_t origin_x,
                               size_t origin_y);
 
+/**
+ * Tries to turn a [BitmapCommand] into a [Packet].
+ *
+ * Returns: NULL or a [Packet] containing the command.
+ */
+Packet *sp_cmd_bitmap_try_into_packet(BitmapCommand */*notnull*/ command);
+
+/**
+ * Clones an [BitVecCommand] instance.
+ *
+ * returns: a new [BitVecCommand] instance.
+ */
 BitVecCommand */*notnull*/ sp_cmd_bitvec_clone(BitVecCommand */*notnull*/ command);
 
+/**
+ * Deallocates a [BitVecCommand].
+ */
 void sp_cmd_bitvec_free(BitVecCommand */*notnull*/ command);
 
-DisplayBitVec *sp_cmd_bitvec_get(BitVecCommand */*notnull*/ command);
+/**
+ * Returns a pointer to the [BitVec] contained in the [BitVecCommand].
+ */
+BitVec *sp_cmd_bitvec_get(BitVecCommand */*notnull*/ command);
 
+/**
+ * Reads the compression kind of the [BitVecCommand].
+ */
 CompressionCode sp_cmd_bitvec_get_compression(BitVecCommand */*notnull*/ command);
 
+/**
+ * Reads the offset field of the [BitVecCommand].
+ */
 Offset sp_cmd_bitvec_get_offset(BitVecCommand */*notnull*/ command);
 
+/**
+ * Returns the [BinaryOperation] of the command.
+ */
 BinaryOperation sp_cmd_bitvec_get_operation(BitVecCommand */*notnull*/ command);
 
-Packet *sp_cmd_bitvec_into_packet(BitVecCommand */*notnull*/ command);
-
 /**
  * Set pixel data starting at the pixel offset on screen.
  *
@@ -1194,34 +1250,60 @@ Packet *sp_cmd_bitvec_into_packet(BitVecCommand */*notnull*/ command);
  *
  * The contained [`DisplayBitVec`] is always uncompressed.
  */
-BitVecCommand */*notnull*/ sp_cmd_bitvec_new(DisplayBitVec */*notnull*/ bitvec,
+BitVecCommand */*notnull*/ sp_cmd_bitvec_new(BitVec */*notnull*/ bitvec,
                                              size_t offset,
                                              BinaryOperation operation,
                                              CompressionCode compression);
 
 /**
- * Moves the provided bitmap to be contained in the command.
+ * Moves the provided [BitVec] to be contained in the [BitVecCommand].
  */
 void sp_cmd_bitvec_set(BitVecCommand */*notnull*/ command,
-                       DisplayBitVec */*notnull*/ bitvec);
+                       BitVec */*notnull*/ bitvec);
 
+/**
+ * Overwrites the compression kind of the [BitVecCommand].
+ */
 void sp_cmd_bitvec_set_compression(BitVecCommand */*notnull*/ command,
                                    CompressionCode compression);
 
+/**
+ * Overwrites the offset field of the [BitVecCommand].
+ */
 void sp_cmd_bitvec_set_offset(BitVecCommand */*notnull*/ command,
                               Offset offset);
 
+/**
+ * Overwrites the [BinaryOperation] of the command.
+ */
 void sp_cmd_bitvec_set_operation(BitVecCommand */*notnull*/ command,
                                  BinaryOperation operation);
 
+/**
+ * Tries to turn a [BitVecCommand] into a [Packet].
+ *
+ * Returns: NULL or a [Packet] containing the command.
+ */
+Packet *sp_cmd_bitvec_try_into_packet(BitVecCommand */*notnull*/ command);
+
+/**
+ * Clones an [GlobalBrightnessCommand] instance.
+ *
+ * returns: a new [GlobalBrightnessCommand] instance.
+ */
 GlobalBrightnessCommand */*notnull*/ sp_cmd_brightness_global_clone(GlobalBrightnessCommand */*notnull*/ command);
 
 void sp_cmd_brightness_global_free(BitmapCommand */*notnull*/ command);
 
 Brightness *sp_cmd_brightness_global_get(GlobalBrightnessCommand */*notnull*/ command);
 
-Packet *sp_cmd_brightness_global_into_packet(GlobalBrightnessCommand */*notnull*/ command);
+Packet */*notnull*/ sp_cmd_brightness_global_into_packet(GlobalBrightnessCommand */*notnull*/ command);
 
+/**
+ * Set the brightness of all tiles to the same value.
+ *
+ * Returns: a new [GlobalBrightnessCommand] instance.
+ */
 GlobalBrightnessCommand */*notnull*/ sp_cmd_brightness_global_new(Brightness brightness);
 
 /**
@@ -1230,62 +1312,131 @@ GlobalBrightnessCommand */*notnull*/ sp_cmd_brightness_global_new(Brightness bri
 void sp_cmd_brightness_global_set(GlobalBrightnessCommand */*notnull*/ command,
                                   Brightness brightness);
 
+/**
+ * Clones an [BrightnessGridCommand] instance.
+ *
+ * returns: a new [BrightnessGridCommand] instance.
+ */
 BrightnessGridCommand */*notnull*/ sp_cmd_brightness_grid_clone(BrightnessGridCommand */*notnull*/ command);
 
+/**
+ * Deallocates a [BitmapCommand].
+ */
 void sp_cmd_brightness_grid_free(BitmapCommand */*notnull*/ command);
 
+/**
+ * Moves the provided [BrightnessGrid] into a new [BrightnessGridCommand],
+ * leaving other fields as their default values.
+ */
 BrightnessGridCommand */*notnull*/ sp_cmd_brightness_grid_from_grid(BrightnessGrid */*notnull*/ grid);
 
+/**
+ * Returns a pointer to the [BrightnessGrid] contained in the [BrightnessGridCommand].
+ */
 BrightnessGrid *sp_cmd_brightness_grid_get(BrightnessGridCommand */*notnull*/ command);
 
+/**
+ * Overwrites the origin field of the [BrightnessGridCommand].
+ */
 void sp_cmd_brightness_grid_get_origin(BrightnessGridCommand */*notnull*/ command,
                                        size_t */*notnull*/ origin_x,
                                        size_t */*notnull*/ origin_y);
 
+/**
+ * Tries to turn a [BrightnessGridCommand] into a [Packet].
+ *
+ * Returns: NULL or a [Packet] containing the command.
+ */
 Packet *sp_cmd_brightness_grid_into_packet(BrightnessGridCommand */*notnull*/ command);
 
+/**
+ * Set the brightness of individual tiles in a rectangular area of the display.
+ *
+ * The passed [BrightnessGrid] gets consumed.
+ *
+ * Returns: a new [BrightnessGridCommand] instance.
+ */
 BrightnessGridCommand */*notnull*/ sp_cmd_brightness_grid_new(BrightnessGrid */*notnull*/ grid,
                                                               size_t origin_x,
                                                               size_t origin_y);
 
 /**
- * Moves the provided bitmap to be contained in the command.
+ * Moves the provided [BrightnessGrid] to be contained in the [BrightnessGridCommand].
  */
 void sp_cmd_brightness_grid_set(BrightnessGridCommand */*notnull*/ command,
                                 BrightnessGrid */*notnull*/ grid);
 
+/**
+ * Reads the origin field of the [BrightnessGridCommand].
+ */
 void sp_cmd_brightness_grid_set_origin(BrightnessGridCommand */*notnull*/ command,
                                        size_t origin_x,
                                        size_t origin_y);
 
+/**
+ * Clones an [CharGridCommand] instance.
+ *
+ * returns: a new [CharGridCommand] instance.
+ */
 CharGridCommand */*notnull*/ sp_cmd_char_grid_clone(CharGridCommand */*notnull*/ command);
 
+/**
+ * Deallocates a [BitmapCommand].
+ */
 void sp_cmd_char_grid_free(BitmapCommand */*notnull*/ command);
 
+/**
+ * Moves the provided [CharGrid] into a new [CharGridCommand],
+ * leaving other fields as their default values.
+ */
 CharGridCommand */*notnull*/ sp_cmd_char_grid_from_grid(CharGrid */*notnull*/ grid);
 
+/**
+ * Returns a pointer to the [CharGrid] contained in the [CharGridCommand].
+ */
 CharGrid *sp_cmd_char_grid_get(CharGridCommand */*notnull*/ command);
 
+/**
+ * Reads the origin field of the [CharGridCommand].
+ */
 void sp_cmd_char_grid_get_origin(CharGridCommand */*notnull*/ command,
                                  size_t */*notnull*/ origin_x,
                                  size_t */*notnull*/ origin_y);
 
-Packet *sp_cmd_char_grid_into_packet(CharGridCommand */*notnull*/ command);
+/**
-
+ * Show UTF-8 encoded text on the screen.
+ *
+ * The passed [CharGrid] gets consumed.
+ *
+ * Returns: a new [CharGridCommand] instance.
+ */
 CharGridCommand */*notnull*/ sp_cmd_char_grid_new(CharGrid */*notnull*/ grid,
                                                   size_t origin_x,
                                                   size_t origin_y);
 
 /**
- * Moves the provided bitmap to be contained in the command.
+ * Moves the provided [CharGrid] to be contained in the [CharGridCommand].
  */
 void sp_cmd_char_grid_set(CharGridCommand */*notnull*/ command,
                           CharGrid */*notnull*/ grid);
 
+/**
+ * Overwrites the origin field of the [CharGridCommand].
+ */
 void sp_cmd_char_grid_set_origin(CharGridCommand */*notnull*/ command,
                                  size_t origin_x,
                                  size_t origin_y);
 
+/**
+ * Tries to turn a [CharGridCommand] into a [Packet].
+ *
+ * Returns: NULL or a [Packet] containing the command.
+ */
+Packet *sp_cmd_char_grid_try_into_packet(CharGridCommand */*notnull*/ command);
+
+/**
+ * Deallocates a [ClearCommand].
+ */
 void sp_cmd_clear_free(ClearCommand */*notnull*/ command);
 
 /**
@@ -1294,43 +1445,84 @@ void sp_cmd_clear_free(ClearCommand */*notnull*/ command);
  * Does not affect brightness.
  *
  * Returns: a new [ClearCommand] instance.
- *
- * # Examples
- *
- * ```C
- * sp_udp_send_command(connection, sp_cmd_clear());
- * ```
  */
 ClearCommand */*notnull*/ sp_cmd_clear_new(void);
 
+/**
+ * Clones an [Cp437GridCommand] instance.
+ *
+ * returns: a new [Cp437GridCommand] instance.
+ */
 Cp437GridCommand */*notnull*/ sp_cmd_cp437_grid_clone(Cp437GridCommand */*notnull*/ command);
 
+/**
+ * Deallocates a [Cp437GridCommand].
+ */
 void sp_cmd_cp437_grid_free(BitmapCommand */*notnull*/ command);
 
+/**
+ * Moves the provided [Cp437Grid] into a new [Cp437GridCommand],
+ * leaving other fields as their default values.
+ */
 Cp437GridCommand */*notnull*/ sp_cmd_cp437_grid_from_grid(Cp437Grid */*notnull*/ grid);
 
+/**
+ * Show text on the screen.
+ *
+ * The text is sent in the form of a 2D grid of [CP-437] encoded characters.
+ * For sending UTF-8 encoded characters, see [servicepoint::CharGridCommand].
+ *
+ * [CP-437]: https://en.wikipedia.org/wiki/Code_page_437
+ */
 Cp437Grid *sp_cmd_cp437_grid_get(Cp437GridCommand */*notnull*/ command);
 
+/**
+ * Gets the origin field of the [Cp437GridCommand].
+ *
+ * Rust equivalent: `cp437_command.origin`
+ */
 void sp_cmd_cp437_grid_get_origin(Cp437GridCommand */*notnull*/ command,
                                   size_t */*notnull*/ origin_x,
                                   size_t */*notnull*/ origin_y);
 
-Packet *sp_cmd_cp437_grid_into_packet(Cp437GridCommand */*notnull*/ command);
+/**
-
+ * Show text on the screen.
+ *
+ * The text is sent in the form of a 2D grid of [CP-437] encoded characters.
+ *
+ * The origin is relative to the top-left of the display.
+ */
 Cp437GridCommand */*notnull*/ sp_cmd_cp437_grid_new(Cp437Grid */*notnull*/ grid,
                                                     size_t origin_x,
                                                     size_t origin_y);
 
 /**
- * Moves the provided bitmap to be contained in the command.
+ * Moves the provided bitmap into the provided command.
+ *
+ * This drops the previously contained [Cp437Grid].
  */
 void sp_cmd_cp437_grid_set(Cp437GridCommand */*notnull*/ command,
                            Cp437Grid */*notnull*/ grid);
 
+/**
+ * Sets the origin field of the [Cp437GridCommand].
+ *
+ * Rust equivalent: `cp437_command.origin = Origin::new(origin_x, origin_y)`
+ */
 void sp_cmd_cp437_grid_set_origin(Cp437GridCommand */*notnull*/ command,
                                   size_t origin_x,
                                   size_t origin_y);
 
+/**
+ * Tries to turn a [Cp437GridCommand] into a [Packet].
+ *
+ * Returns: NULL or a [Packet] containing the command.
+ */
+Packet *sp_cmd_cp437_grid_try_into_packet(Cp437GridCommand */*notnull*/ command);
+
+/**
+ * Deallocates a [FadeOutCommand].
+ */
 void sp_cmd_fade_out_free(ClearCommand */*notnull*/ command);
 
 /**
@@ -1341,32 +1533,44 @@ void sp_cmd_fade_out_free(ClearCommand */*notnull*/ command);
 FadeOutCommand */*notnull*/ sp_cmd_fade_out_new(void);
 
 /**
- * Clones a [SPCommand] instance.
+ * Clones an [SPCommand] instance.
  *
- * returns: new [SPCommand] instance.
+ * returns: a new [SPCommand] instance.
  */
-SPCommand sp_cmd_generic_clone(SPCommand command);
+Command sp_cmd_generic_clone(Command command);
 
 /**
- * Deallocates a [SPCommand].
+ * Deallocates an [SPCommand].
  *
  * # Examples
  *
  * ```C
- * TypedCommand c = sp_command_clear();
+ * SPCommand c = sp_cmd_clear_into_generic(sp_cmd_clear_new());
  * sp_command_free(c);
  * ```
  */
-void sp_cmd_generic_free(SPCommand command);
+void sp_cmd_generic_free(Command command);
 
 /**
- * Turns a [TypedCommand] into a [Packet].
+ * Tries to turn a [SPCommand] into a [Packet].
- * The [TypedCommand] gets consumed.
+ * The [SPCommand] gets consumed.
  *
- * Returns NULL in case of an error.
+ * Returns tag [CommandTag::Invalid] in case of an error.
  */
-Packet *sp_cmd_generic_into_packet(SPCommand command);
+Packet *sp_cmd_generic_into_packet(Command command);
 
+/**
+ * Tries to turn a [Packet] into a [SPCommand].
+ *
+ * The packet is dropped in the process.
+ *
+ * Returns: pointer to new [SPCommand] instance or NULL if parsing failed.
+ */
+Command *sp_cmd_generic_try_from_packet(Packet */*notnull*/ packet);
+
+/**
+ * Deallocates a [HardResetCommand].
+ */
 void sp_cmd_hard_reset_free(ClearCommand */*notnull*/ command);
 
 /**
@@ -1484,6 +1688,8 @@ size_t sp_cp437_grid_width(Cp437Grid */*notnull*/ cp437_grid);
 
 /**
  * Clones a [Packet].
+ *
+ * returns: a new [Packet] instance.
  */
 Packet */*notnull*/ sp_packet_clone(Packet */*notnull*/ packet);
 
@@ -1585,7 +1791,7 @@ UdpSocket *sp_udp_open_ipv4(uint8_t ip1,
                             uint16_t port);
 
 /**
- * Sends a [TypedCommand] to the display using the [UdpSocket].
+ * Sends a [SPCommand] to the display using the [UdpSocket].
  *
  * The passed `command` gets consumed.
  *
@@ -1597,7 +1803,7 @@ UdpSocket *sp_udp_open_ipv4(uint8_t ip1,
  * sp_udp_send_command(connection, sp_command_brightness(5));
  * ```
  */
-bool sp_udp_send_command(UdpSocket */*notnull*/ connection, SPCommand command);
+bool sp_udp_send_command(UdpSocket */*notnull*/ connection, Command command);
 
 /**
  * Sends a [Header] to the display using the [UdpSocket].

src/commands/bitmap_command.rs

@@ -1,4 +1,4 @@
-use crate::{
+use crate::mem::{
     heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove,
 };
 use servicepoint::{Bitmap, BitmapCommand, CompressionCode, Origin, Packet};
@@ -26,7 +26,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_new(
 /// Move the provided [Bitmap] into a new [BitmapCommand],
 /// leaving other fields as their default values.
 ///
-/// Rust equivalent: [`<BitmapCommand as From<Bitmap>>::from`]
+/// Rust equivalent: `BitmapCommand::from(bitmap)`
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitmap_from_bitmap(
     bitmap: NonNull<Bitmap>,
@@ -34,13 +34,19 @@ pub unsafe extern "C" fn sp_cmd_bitmap_from_bitmap(
     heap_move_nonnull(unsafe { heap_remove(bitmap) }.into())
 }
 
+/// Tries to turn a [BitmapCommand] into a [Packet].
+///
+/// Returns: NULL or a [Packet] containing the command.
 #[no_mangle]
-pub unsafe extern "C" fn sp_cmd_bitmap_into_packet(
+pub unsafe extern "C" fn sp_cmd_bitmap_try_into_packet(
     command: NonNull<BitmapCommand>,
 ) -> *mut Packet {
     heap_move_ok(unsafe { heap_remove(command) }.try_into())
 }
 
+/// Clones an [BitmapCommand] instance.
+///
+/// returns: a new [BitmapCommand] instance.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitmap_clone(
     command: NonNull<BitmapCommand>,
@@ -48,6 +54,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_clone(
     unsafe { heap_clone(command) }
 }
 
+/// Deallocates a [BitmapCommand] instance.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitmap_free(command: NonNull<BitmapCommand>) {
     unsafe { heap_drop(command) }
@@ -66,7 +73,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_get(
     unsafe { NonNull::from(&mut (command.as_mut().bitmap)) }
 }
 
-/// Moves the provided bitmap to be contained in the command.
+/// Moves the provided [Bitmap] to be contained in the [BitmapCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitmap_set(
     mut command: NonNull<BitmapCommand>,
@@ -77,6 +84,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_set(
     }
 }
 
+/// Reads the origin field of the [BitmapCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitmap_get_origin(
     command: NonNull<BitmapCommand>,
@@ -90,6 +98,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_get_origin(
     }
 }
 
+/// Overwrites the origin field of the [BitmapCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitmap_set_origin(
     mut command: NonNull<BitmapCommand>,
@@ -101,6 +110,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_set_origin(
     }
 }
 
+/// Overwrites the compression kind of the [BitmapCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitmap_set_compression(
     mut command: NonNull<BitmapCommand>,
@@ -111,6 +121,7 @@ pub unsafe extern "C" fn sp_cmd_bitmap_set_compression(
     }
 }
 
+/// Reads the compression kind of the [BitmapCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitmap_get_compression(
     command: NonNull<BitmapCommand>,

src/commands/bitvec_command.rs

@@ -1,4 +1,4 @@
-use crate::{
+use crate::mem::{
     heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove,
 };
 use servicepoint::{
@@ -34,13 +34,19 @@ pub unsafe extern "C" fn sp_cmd_bitvec_new(
     })
 }
 
+/// Tries to turn a [BitVecCommand] into a [Packet].
+///
+/// Returns: NULL or a [Packet] containing the command.
 #[no_mangle]
-pub unsafe extern "C" fn sp_cmd_bitvec_into_packet(
+pub unsafe extern "C" fn sp_cmd_bitvec_try_into_packet(
     command: NonNull<BitVecCommand>,
 ) -> *mut Packet {
     heap_move_ok(unsafe { heap_remove(command) }.try_into())
 }
 
+/// Clones an [BitVecCommand] instance.
+///
+/// returns: a new [BitVecCommand] instance.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitvec_clone(
     command: NonNull<BitVecCommand>,
@@ -48,11 +54,13 @@ pub unsafe extern "C" fn sp_cmd_bitvec_clone(
     unsafe { heap_clone(command) }
 }
 
+/// Deallocates a [BitVecCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitvec_free(command: NonNull<BitVecCommand>) {
     unsafe { heap_drop(command) }
 }
 
+/// Returns a pointer to the [BitVec] contained in the [BitVecCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitvec_get(
     mut command: NonNull<BitVecCommand>,
@@ -60,7 +68,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_get(
     &mut unsafe { command.as_mut() }.bitvec
 }
 
-/// Moves the provided bitmap to be contained in the command.
+/// Moves the provided [BitVec] to be contained in the [BitVecCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitvec_set(
     mut command: NonNull<BitVecCommand>,
@@ -71,6 +79,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_set(
     }
 }
 
+/// Reads the offset field of the [BitVecCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitvec_get_offset(
     command: NonNull<BitVecCommand>,
@@ -78,6 +87,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_get_offset(
     unsafe { command.as_ref().offset }
 }
 
+/// Overwrites the offset field of the [BitVecCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitvec_set_offset(
     mut command: NonNull<BitVecCommand>,
@@ -88,6 +98,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_set_offset(
     }
 }
 
+/// Returns the [BinaryOperation] of the command.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitvec_get_operation(
     command: NonNull<BitVecCommand>,
@@ -95,6 +106,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_get_operation(
     unsafe { command.as_ref().operation.clone() } // TODO remove clone
 }
 
+/// Overwrites the [BinaryOperation] of the command.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitvec_set_operation(
     mut command: NonNull<BitVecCommand>,
@@ -105,6 +117,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_set_operation(
     }
 }
 
+/// Overwrites the compression kind of the [BitVecCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitvec_set_compression(
     mut command: NonNull<BitVecCommand>,
@@ -115,6 +128,7 @@ pub unsafe extern "C" fn sp_cmd_bitvec_set_compression(
     }
 }
 
+/// Reads the compression kind of the [BitVecCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_bitvec_get_compression(
     command: NonNull<BitVecCommand>,

src/commands/brightness_grid_command.rs

@@ -1,4 +1,4 @@
-use crate::{
+use crate::mem::{
     heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove,
 };
 use servicepoint::{
@@ -6,6 +6,11 @@ use servicepoint::{
 };
 use std::ptr::NonNull;
 
+/// Set the brightness of individual tiles in a rectangular area of the display.
+///
+/// The passed [BrightnessGrid] gets consumed.
+///
+/// Returns: a new [BrightnessGridCommand] instance.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_brightness_grid_new(
     grid: NonNull<BrightnessGrid>,
@@ -18,6 +23,8 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_new(
     })
 }
 
+/// Moves the provided [BrightnessGrid] into a new [BrightnessGridCommand],
+/// leaving other fields as their default values.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_brightness_grid_from_grid(
     grid: NonNull<BrightnessGrid>,
@@ -25,6 +32,9 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_from_grid(
     heap_move_nonnull(unsafe { heap_remove(grid) }.into())
 }
 
+/// Tries to turn a [BrightnessGridCommand] into a [Packet].
+///
+/// Returns: NULL or a [Packet] containing the command.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_brightness_grid_into_packet(
     command: NonNull<BrightnessGridCommand>,
@@ -32,6 +42,9 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_into_packet(
     heap_move_ok(unsafe { heap_remove(command) }.try_into())
 }
 
+/// Clones an [BrightnessGridCommand] instance.
+///
+/// returns: a new [BrightnessGridCommand] instance.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_brightness_grid_clone(
     command: NonNull<BrightnessGridCommand>,
@@ -39,6 +52,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_clone(
     unsafe { heap_clone(command) }
 }
 
+/// Deallocates a [BitmapCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_brightness_grid_free(
     command: NonNull<BitmapCommand>,
@@ -46,7 +60,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_free(
     unsafe { heap_drop(command) }
 }
 
-/// Moves the provided bitmap to be contained in the command.
+/// Moves the provided [BrightnessGrid] to be contained in the [BrightnessGridCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_brightness_grid_set(
     mut command: NonNull<BrightnessGridCommand>,
@@ -57,6 +71,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_set(
     }
 }
 
+/// Returns a pointer to the [BrightnessGrid] contained in the [BrightnessGridCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_brightness_grid_get(
     mut command: NonNull<BrightnessGridCommand>,
@@ -64,6 +79,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_get(
     &mut unsafe { command.as_mut() }.grid
 }
 
+/// Overwrites the origin field of the [BrightnessGridCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_brightness_grid_get_origin(
     command: NonNull<BrightnessGridCommand>,
@@ -77,6 +93,7 @@ pub unsafe extern "C" fn sp_cmd_brightness_grid_get_origin(
     }
 }
 
+/// Reads the origin field of the [BrightnessGridCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_brightness_grid_set_origin(
     mut command: NonNull<BrightnessGridCommand>,

src/commands/cc_only_commands.rs

@@ -1,4 +1,4 @@
-use crate::{heap_drop, heap_move_nonnull};
+use crate::mem::{heap_drop, heap_move_nonnull};
 use servicepoint::{ClearCommand, FadeOutCommand, HardResetCommand};
 use std::ptr::NonNull;
 
@@ -7,17 +7,12 @@ use std::ptr::NonNull;
 /// Does not affect brightness.
 ///
 /// Returns: a new [ClearCommand] instance.
-///
-/// # Examples
-///
-/// ```C
-/// sp_udp_send_command(connection, sp_cmd_clear());
-/// ```
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_clear_new() -> NonNull<ClearCommand> {
     heap_move_nonnull(ClearCommand)
 }
 
+/// Deallocates a [ClearCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_clear_free(command: NonNull<ClearCommand>) {
     unsafe { heap_drop(command) }
@@ -33,6 +28,7 @@ pub unsafe extern "C" fn sp_cmd_hard_reset_new() -> NonNull<HardResetCommand> {
     heap_move_nonnull(HardResetCommand)
 }
 
+/// Deallocates a [HardResetCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_hard_reset_free(
     command: NonNull<ClearCommand>,
@@ -48,6 +44,7 @@ pub unsafe extern "C" fn sp_cmd_fade_out_new() -> NonNull<FadeOutCommand> {
     heap_move_nonnull(FadeOutCommand)
 }
 
+/// Deallocates a [FadeOutCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_fade_out_free(command: NonNull<ClearCommand>) {
     unsafe { heap_drop(command) }

src/commands/char_grid_command.rs

@@ -1,9 +1,14 @@
-use crate::{
+use crate::mem::{
     heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove,
 };
 use servicepoint::{BitmapCommand, CharGrid, CharGridCommand, Origin, Packet};
 use std::ptr::NonNull;
 
+/// Show UTF-8 encoded text on the screen.
+///
+/// The passed [CharGrid] gets consumed.
+///
+/// Returns: a new [CharGridCommand] instance.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_char_grid_new(
     grid: NonNull<CharGrid>,
@@ -16,6 +21,8 @@ pub unsafe extern "C" fn sp_cmd_char_grid_new(
     })
 }
 
+/// Moves the provided [CharGrid] into a new [CharGridCommand],
+/// leaving other fields as their default values.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_char_grid_from_grid(
     grid: NonNull<CharGrid>,
@@ -23,13 +30,19 @@ pub unsafe extern "C" fn sp_cmd_char_grid_from_grid(
     heap_move_nonnull(unsafe { heap_remove(grid) }.into())
 }
 
+/// Tries to turn a [CharGridCommand] into a [Packet].
+///
+/// Returns: NULL or a [Packet] containing the command.
 #[no_mangle]
-pub unsafe extern "C" fn sp_cmd_char_grid_into_packet(
+pub unsafe extern "C" fn sp_cmd_char_grid_try_into_packet(
     command: NonNull<CharGridCommand>,
 ) -> *mut Packet {
     heap_move_ok(unsafe { heap_remove(command) }.try_into())
 }
 
+/// Clones an [CharGridCommand] instance.
+///
+/// returns: a new [CharGridCommand] instance.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_char_grid_clone(
     command: NonNull<CharGridCommand>,
@@ -37,6 +50,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_clone(
     unsafe { heap_clone(command) }
 }
 
+/// Deallocates a [BitmapCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_char_grid_free(
     command: NonNull<BitmapCommand>,
@@ -44,7 +58,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_free(
     unsafe { heap_drop(command) }
 }
 
-/// Moves the provided bitmap to be contained in the command.
+/// Moves the provided [CharGrid] to be contained in the [CharGridCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_char_grid_set(
     mut command: NonNull<CharGridCommand>,
@@ -55,6 +69,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_set(
     }
 }
 
+/// Returns a pointer to the [CharGrid] contained in the [CharGridCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_char_grid_get(
     mut command: NonNull<CharGridCommand>,
@@ -62,6 +77,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_get(
     &mut unsafe { command.as_mut() }.grid
 }
 
+/// Reads the origin field of the [CharGridCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_char_grid_get_origin(
     command: NonNull<CharGridCommand>,
@@ -75,6 +91,7 @@ pub unsafe extern "C" fn sp_cmd_char_grid_get_origin(
     }
 }
 
+/// Overwrites the origin field of the [CharGridCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_char_grid_set_origin(
     mut command: NonNull<CharGridCommand>,

src/commands/cp437_grid_command.rs

@@ -1,4 +1,4 @@
-use crate::{
+use crate::mem::{
     heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove,
 };
 use servicepoint::{
@@ -6,6 +6,11 @@ use servicepoint::{
 };
 use std::ptr::NonNull;
 
+/// Show text on the screen.
+///
+/// The text is sent in the form of a 2D grid of [CP-437] encoded characters.
+///
+/// The origin is relative to the top-left of the display.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_cp437_grid_new(
     grid: NonNull<Cp437Grid>,
@@ -18,6 +23,8 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_new(
     })
 }
 
+/// Moves the provided [Cp437Grid] into a new [Cp437GridCommand],
+/// leaving other fields as their default values.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_cp437_grid_from_grid(
     grid: NonNull<Cp437Grid>,
@@ -25,13 +32,19 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_from_grid(
     heap_move_nonnull(unsafe { heap_remove(grid) }.into())
 }
 
+/// Tries to turn a [Cp437GridCommand] into a [Packet].
+///
+/// Returns: NULL or a [Packet] containing the command.
 #[no_mangle]
-pub unsafe extern "C" fn sp_cmd_cp437_grid_into_packet(
+pub unsafe extern "C" fn sp_cmd_cp437_grid_try_into_packet(
     command: NonNull<Cp437GridCommand>,
 ) -> *mut Packet {
     heap_move_ok(unsafe { heap_remove(command) }.try_into())
 }
 
+/// Clones an [Cp437GridCommand] instance.
+///
+/// returns: a new [Cp437GridCommand] instance.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_cp437_grid_clone(
     command: NonNull<Cp437GridCommand>,
@@ -39,6 +52,7 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_clone(
     unsafe { heap_clone(command) }
 }
 
+/// Deallocates a [Cp437GridCommand].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_cp437_grid_free(
     command: NonNull<BitmapCommand>,
@@ -46,7 +60,9 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_free(
     unsafe { heap_drop(command) }
 }
 
-/// Moves the provided bitmap to be contained in the command.
+/// Moves the provided bitmap into the provided command.
+///
+/// This drops the previously contained [Cp437Grid].
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_cp437_grid_set(
     mut command: NonNull<Cp437GridCommand>,
@@ -57,6 +73,12 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_set(
     }
 }
 
+/// Show text on the screen.
+///
+/// The text is sent in the form of a 2D grid of [CP-437] encoded characters.
+/// For sending UTF-8 encoded characters, see [servicepoint::CharGridCommand].
+///
+/// [CP-437]: https://en.wikipedia.org/wiki/Code_page_437
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_cp437_grid_get(
     mut command: NonNull<Cp437GridCommand>,
@@ -64,6 +86,9 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_get(
     &mut unsafe { command.as_mut() }.grid
 }
 
+/// Gets the origin field of the [Cp437GridCommand].
+///
+/// Rust equivalent: `cp437_command.origin`
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_cp437_grid_get_origin(
     command: NonNull<Cp437GridCommand>,
@@ -77,6 +102,9 @@ pub unsafe extern "C" fn sp_cmd_cp437_grid_get_origin(
     }
 }
 
+/// Sets the origin field of the [Cp437GridCommand].
+///
+/// Rust equivalent: `cp437_command.origin = Origin::new(origin_x, origin_y)`
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_cp437_grid_set_origin(
     mut command: NonNull<Cp437GridCommand>,

src/commands/generic_command.rs

@@ -1,14 +1,17 @@
-use crate::{
+use crate::mem::{
-    heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove,
+    heap_clone, heap_drop, heap_move, heap_move_nonnull, heap_move_ok,
+    heap_remove,
 };
 use servicepoint::{
-    BitVecCommand, BitmapCommand, BrightnessGridCommand,
+    BitVecCommand, BitmapCommand, BrightnessGridCommand, CharGridCommand,
-    CharGridCommand, ClearCommand, Cp437GridCommand, FadeOutCommand,
+    ClearCommand, Cp437GridCommand, FadeOutCommand, GlobalBrightnessCommand,
-    GlobalBrightnessCommand, HardResetCommand, Packet, TypedCommand,
+    HardResetCommand, Packet, TypedCommand,
 };
 use std::ptr::{null_mut, NonNull};
 
+/// Pointer to one of the available command structs.
 #[repr(C)]
+#[allow(missing_docs)]
 pub union CommandUnion {
     pub null: *mut u8,
     pub bitmap: NonNull<BitmapCommand>,
@@ -24,7 +27,11 @@ pub union CommandUnion {
     pub fade_out: NonNull<FadeOutCommand>,
 }
 
+/// Specifies the kind of command struct.
+///
+/// This is _not_ equivalent to the [servicepoint::CommandCode]s.
 #[repr(u8)]
+#[allow(missing_docs)]
 pub enum CommandTag {
     Invalid = 0,
     Bitmap,
@@ -39,6 +46,11 @@ pub enum CommandTag {
     BitmapLegacy,
 }
 
+/// This struct represents a pointer to one of the possible command structs.
+///
+/// Only ever access `data` with the correct data type as specified by `tag`!
+///
+/// Rust equivalent: [TypedCommand].
 #[repr(C)]
 pub struct SPCommand {
     /// Specifies which kind of command struct is contained in `data`
@@ -54,12 +66,12 @@ impl SPCommand {
     };
 }
 
-/// Tries to turn a [Packet] into a [TypedCommand].
+/// Tries to turn a [Packet] into a [SPCommand].
 ///
-/// The packet is deallocated in the process.
+/// The packet is dropped in the process.
 ///
-/// Returns: pointer to new [TypedCommand] instance or NULL if parsing failed.
+/// Returns: pointer to new [SPCommand] instance or NULL if parsing failed.
-/// #[no_mangle]
+#[no_mangle]
 pub unsafe extern "C" fn sp_cmd_generic_try_from_packet(
     packet: NonNull<Packet>,
 ) -> *mut SPCommand {
@@ -131,9 +143,9 @@ pub unsafe extern "C" fn sp_cmd_generic_try_from_packet(
     }))
 }
 
-/// Clones a [SPCommand] instance.
+/// Clones an [SPCommand] instance.
 ///
-/// returns: new [SPCommand] instance.
+/// returns: a new [SPCommand] instance.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_generic_clone(command: SPCommand) -> SPCommand {
     unsafe {
@@ -206,19 +218,19 @@ pub unsafe extern "C" fn sp_cmd_generic_clone(command: SPCommand) -> SPCommand {
     }
 }
 
-/// Deallocates a [SPCommand].
+/// Deallocates an [SPCommand].
 ///
 /// # Examples
 ///
 /// ```C
-/// TypedCommand c = sp_command_clear();
+/// SPCommand c = sp_cmd_clear_into_generic(sp_cmd_clear_new());
 /// sp_command_free(c);
 /// ```
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_generic_free(command: SPCommand) {
     unsafe {
         match command.tag {
-            CommandTag::Invalid => return,
+            CommandTag::Invalid => (),
             CommandTag::Bitmap => heap_drop(command.data.bitmap),
             CommandTag::BitVec => heap_drop(command.data.bitvec),
             CommandTag::BrightnessGrid => {
@@ -237,10 +249,10 @@ pub unsafe extern "C" fn sp_cmd_generic_free(command: SPCommand) {
     }
 }
 
-/// Turns a [TypedCommand] into a [Packet].
+/// Tries to turn a [SPCommand] into a [Packet].
-/// The [TypedCommand] gets consumed.
+/// The [SPCommand] gets consumed.
 ///
-/// Returns NULL in case of an error.
+/// Returns tag [CommandTag::Invalid] in case of an error.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_generic_into_packet(
     command: SPCommand,
@@ -262,20 +274,20 @@ pub unsafe extern "C" fn sp_cmd_generic_into_packet(
         CommandTag::Cp437Grid => heap_move_ok(unsafe {
             heap_remove(command.data.cp437_grid).try_into()
         }),
-        CommandTag::GlobalBrightness => heap_move_ok(unsafe {
+        CommandTag::GlobalBrightness => heap_move(unsafe {
-            heap_remove(command.data.global_brightness).try_into()
+            heap_remove(command.data.global_brightness).into()
         }),
         CommandTag::Clear => {
-            heap_move_ok(unsafe { heap_remove(command.data.clear).try_into() })
+            heap_move(unsafe { heap_remove(command.data.clear).into() })
+        }
+        CommandTag::HardReset => {
+            heap_move(unsafe { heap_remove(command.data.hard_reset).into() })
+        }
+        CommandTag::FadeOut => {
+            heap_move(unsafe { heap_remove(command.data.fade_out).into() })
+        }
+        CommandTag::BitmapLegacy => {
+            heap_move(unsafe { heap_remove(command.data.bitmap_legacy).into() })
         }
-        CommandTag::HardReset => heap_move_ok(unsafe {
-            heap_remove(command.data.hard_reset).try_into()
-        }),
-        CommandTag::FadeOut => heap_move_ok(unsafe {
-            heap_remove(command.data.fade_out).try_into()
-        }),
-        CommandTag::BitmapLegacy => heap_move_ok(unsafe {
-            heap_remove(command.data.bitmap_legacy).try_into()
-        }),
     }
 }

src/commands/global_brightness_command.rs

@@ -1,11 +1,12 @@
-use crate::{
+use crate::mem::{heap_clone, heap_drop, heap_move_nonnull, heap_remove};
-    heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove,
-};
 use servicepoint::{
     BitmapCommand, Brightness, GlobalBrightnessCommand, Packet,
 };
 use std::ptr::NonNull;
 
+/// Set the brightness of all tiles to the same value.
+///
+/// Returns: a new [GlobalBrightnessCommand] instance.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_brightness_global_new(
     brightness: Brightness,
@@ -16,10 +17,13 @@ pub unsafe extern "C" fn sp_cmd_brightness_global_new(
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_brightness_global_into_packet(
     command: NonNull<GlobalBrightnessCommand>,
-) -> *mut Packet {
+) -> NonNull<Packet> {
-    heap_move_ok(unsafe { heap_remove(command) }.try_into())
+    heap_move_nonnull(unsafe { heap_remove(command) }.into())
 }
 
+/// Clones an [GlobalBrightnessCommand] instance.
+///
+/// returns: a new [GlobalBrightnessCommand] instance.
 #[no_mangle]
 pub unsafe extern "C" fn sp_cmd_brightness_global_clone(
     command: NonNull<GlobalBrightnessCommand>,

src/containers/bitmap.rs

@@ -1,6 +1,13 @@
-use crate::{byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some, heap_remove};
+use crate::{
+    containers::ByteSlice,
+    mem::{
+        heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some,
+        heap_remove,
+    },
+};
 use servicepoint::{
-    Bitmap, BitmapCommand, CompressionCode, DataRef, Grid, Origin, Packet, DisplayBitVec
+    Bitmap, BitmapCommand, CompressionCode, DataRef, DisplayBitVec, Grid,
+    Origin, Packet,
 };
 use std::ptr::NonNull;
 

src/containers/bitvec.rs

@@ -1,19 +1,21 @@
 use crate::{
-    byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull,
+    containers::ByteSlice,
-    heap_move_ok, heap_remove,
+    mem::{
+        heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove,
+    },
 };
 use servicepoint::{
     BinaryOperation, BitVecCommand, CompressionCode, DisplayBitVec, Packet,
 };
 use std::ptr::NonNull;
 
-/// Creates a new [SPBitVec] instance.
+/// Creates a new [DisplayBitVec] instance.
 ///
 /// # Arguments
 ///
 /// - `size`: size in bits.
 ///
-/// returns: [SPBitVec] with all bits set to false.
+/// returns: [DisplayBitVec] with all bits set to false.
 ///
 /// # Panics
 ///
@@ -23,9 +25,9 @@ pub unsafe extern "C" fn sp_bitvec_new(size: usize) -> NonNull<DisplayBitVec> {
     heap_move_nonnull(DisplayBitVec::repeat(false, size))
 }
 
-/// Interpret the data as a series of bits and load then into a new [SPBitVec] instance.
+/// Interpret the data as a series of bits and load then into a new [DisplayBitVec] instance.
 ///
-/// returns: [SPBitVec] instance containing data.
+/// returns: [DisplayBitVec] instance containing data.
 #[no_mangle]
 pub unsafe extern "C" fn sp_bitvec_load(
     data: ByteSlice,
@@ -34,7 +36,7 @@ pub unsafe extern "C" fn sp_bitvec_load(
     heap_move_nonnull(DisplayBitVec::from_slice(data))
 }
 
-/// Clones a [SPBitVec].
+/// Clones a [DisplayBitVec].
 #[no_mangle]
 pub unsafe extern "C" fn sp_bitvec_clone(
     bit_vec: NonNull<DisplayBitVec>,
@@ -42,13 +44,13 @@ pub unsafe extern "C" fn sp_bitvec_clone(
     unsafe { heap_clone(bit_vec) }
 }
 
-/// Deallocates a [SPBitVec].
+/// Deallocates a [DisplayBitVec].
 #[no_mangle]
 pub unsafe extern "C" fn sp_bitvec_free(bit_vec: NonNull<DisplayBitVec>) {
     unsafe { heap_drop(bit_vec) }
 }
 
-/// Gets the value of a bit from the [SPBitVec].
+/// Gets the value of a bit from the [DisplayBitVec].
 ///
 /// # Arguments
 ///
@@ -68,7 +70,7 @@ pub unsafe extern "C" fn sp_bitvec_get(
     unsafe { *bit_vec.as_ref().get(index).unwrap() }
 }
 
-/// Sets the value of a bit in the [SPBitVec].
+/// Sets the value of a bit in the [DisplayBitVec].
 ///
 /// # Arguments
 ///
@@ -88,7 +90,7 @@ pub unsafe extern "C" fn sp_bitvec_set(
     unsafe { (*bit_vec.as_ptr()).set(index, value) }
 }
 
-/// Sets the value of all bits in the [SPBitVec].
+/// Sets the value of all bits in the [DisplayBitVec].
 ///
 /// # Arguments
 ///
@@ -102,7 +104,7 @@ pub unsafe extern "C" fn sp_bitvec_fill(
     unsafe { (*bit_vec.as_ptr()).fill(value) }
 }
 
-/// Gets the length of the [SPBitVec] in bits.
+/// Gets the length of the [DisplayBitVec] in bits.
 ///
 /// # Arguments
 ///
@@ -126,7 +128,7 @@ pub unsafe extern "C" fn sp_bitvec_is_empty(
     unsafe { bit_vec.as_ref().is_empty() }
 }
 
-/// Gets an unsafe reference to the data of the [SPBitVec] instance.
+/// Gets an unsafe reference to the data of the [DisplayBitVec] instance.
 ///
 /// The returned memory is valid for the lifetime of the bitvec.
 ///
@@ -142,7 +144,7 @@ pub unsafe extern "C" fn sp_bitvec_unsafe_data_ref(
 
 /// Creates a [BitVecCommand] and immediately turns that into a [Packet].
 ///
-/// The provided [SPBitVec] gets consumed.
+/// The provided [DisplayBitVec] gets consumed.
 ///
 /// Returns NULL in case of an error.
 #[no_mangle]

src/containers/brightness_grid.rs

@@ -1,6 +1,9 @@
 use crate::{
-    byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull,
+    containers::ByteSlice,
-    heap_move_ok, heap_move_some, heap_remove,
+    mem::{
+        heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some,
+        heap_remove,
+    },
 };
 use servicepoint::{
     Brightness, BrightnessGrid, BrightnessGridCommand, ByteGrid, DataRef, Grid,

src/containers/char_grid.rs

@@ -1,6 +1,8 @@
 use crate::{
-    byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull,
+    containers::ByteSlice,
-    heap_move_ok, heap_remove,
+    mem::{
+        heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_remove,
+    },
 };
 use servicepoint::{CharGrid, CharGridCommand, Grid, Origin, Packet};
 use std::ptr::NonNull;

src/containers/cp437_grid.rs

@@ -1,6 +1,9 @@
 use crate::{
-    byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull,
+    containers::ByteSlice,
-    heap_move_ok, heap_move_some, heap_remove,
+    mem::{
+        heap_clone, heap_drop, heap_move_nonnull, heap_move_ok, heap_move_some,
+        heap_remove,
+    },
 };
 use servicepoint::{
     Cp437Grid, Cp437GridCommand, DataRef, Grid, Origin, Packet,

src/containers/mod.rs

@@ -0,0 +1,13 @@
+mod bitmap;
+mod bitvec;
+mod brightness_grid;
+mod byte_slice;
+mod char_grid;
+mod cp437_grid;
+
+pub use bitmap::*;
+pub use bitvec::*;
+pub use brightness_grid::*;
+pub use byte_slice::*;
+pub use char_grid::*;
+pub use cp437_grid::*;

src/lib.rs

@@ -25,16 +25,14 @@
 //! }
 //! ```
 
-use std::ptr::NonNull;
+/// Functions related to commands.
-
-pub mod bitmap;
-pub mod bitvec;
-pub mod brightness_grid;
-pub mod byte_slice;
-pub mod char_grid;
 pub mod commands;
-pub mod cp437_grid;
+/// Functions related to [servicepoint::Bitmap], [servicepoint::CharGrid] and friends.
+pub mod containers;
+pub(crate) mod mem;
+/// Functions related to [Packet].
 pub mod packet;
+/// Functions related to [UdpSocket].
 pub mod udp;
 
 use std::time::Duration;
@@ -42,34 +40,6 @@ use std::time::Duration;
 /// Actual hardware limit is around 28-29ms/frame. Rounded up for less dropped packets.
 pub const SP_FRAME_PACING_MS: u128 = Duration::from_millis(30).as_millis();
 
-pub(crate) fn heap_move<T>(x: T) -> *mut T {
-    Box::into_raw(Box::new(x))
-}
-
-pub(crate) fn heap_move_nonnull<T>(x: T) -> NonNull<T> {
-    NonNull::from(Box::leak(Box::new(x)))
-}
-
-pub(crate) fn heap_move_ok<T, E>(x: Result<T, E>) -> *mut T {
-    x.map(|x| heap_move(x)).unwrap_or(std::ptr::null_mut())
-}
-
-pub(crate) fn heap_move_some<T>(x: Option<T>) -> *mut T {
-    x.map(|x| heap_move(x)).unwrap_or(std::ptr::null_mut())
-}
-
-pub(crate) unsafe fn heap_drop<T>(x: NonNull<T>) {
-    drop(unsafe { heap_remove(x) });
-}
-
-pub(crate) unsafe fn heap_remove<T>(x: NonNull<T>) -> T {
-    unsafe { *Box::from_raw(x.as_ptr()) }
-}
-
-unsafe fn heap_clone<T: Clone>(source: NonNull<T>) -> NonNull<T> {
-    heap_move_nonnull(unsafe { source.as_ref().clone() })
-}
-
 /// This is a type only used by cbindgen to have a type for pointers.
 pub struct UdpSocket;
 

src/mem.rs

@@ -0,0 +1,29 @@
+use std::ptr::NonNull;
+
+pub(crate) fn heap_move<T>(x: T) -> *mut T {
+    Box::into_raw(Box::new(x))
+}
+
+pub(crate) fn heap_move_nonnull<T>(x: T) -> NonNull<T> {
+    NonNull::from(Box::leak(Box::new(x)))
+}
+
+pub(crate) fn heap_move_ok<T, E>(x: Result<T, E>) -> *mut T {
+    x.map(|x| heap_move(x)).unwrap_or(std::ptr::null_mut())
+}
+
+pub(crate) fn heap_move_some<T>(x: Option<T>) -> *mut T {
+    x.map(|x| heap_move(x)).unwrap_or(std::ptr::null_mut())
+}
+
+pub(crate) unsafe fn heap_drop<T>(x: NonNull<T>) {
+    drop(unsafe { heap_remove(x) });
+}
+
+pub(crate) unsafe fn heap_remove<T>(x: NonNull<T>) -> T {
+    unsafe { *Box::from_raw(x.as_ptr()) }
+}
+
+pub(crate) unsafe fn heap_clone<T: Clone>(source: NonNull<T>) -> NonNull<T> {
+    heap_move_nonnull(unsafe { source.as_ref().clone() })
+}

src/packet.rs

@@ -1,6 +1,6 @@
 use crate::{
-    byte_slice::ByteSlice, heap_clone, heap_drop, heap_move_nonnull,
+    containers::ByteSlice,
-    heap_move_ok,
+    mem::{heap_clone, heap_drop, heap_move_nonnull, heap_move_ok},
 };
 use servicepoint::{CommandCode, Header, Packet};
 use std::ptr::NonNull;
@@ -79,6 +79,8 @@ pub unsafe extern "C" fn sp_packet_serialize_to(
 }
 
 /// Clones a [Packet].
+///
+/// returns: a new [Packet] instance.
 #[no_mangle]
 pub unsafe extern "C" fn sp_packet_clone(
     packet: NonNull<Packet>,

src/udp.rs

@@ -1,9 +1,13 @@
-use crate::commands::{CommandTag, SPCommand};
+use crate::{
-use crate::{heap_drop, heap_move_ok, heap_remove};
+    commands::{CommandTag, SPCommand},
+    mem::{heap_drop, heap_move_ok, heap_remove},
+};
 use servicepoint::{Header, Packet, UdpSocketExt};
-use std::ffi::{c_char, CStr};
+use std::{
-use std::net::{Ipv4Addr, SocketAddrV4, UdpSocket};
+    ffi::{c_char, CStr},
-use std::ptr::NonNull;
+    net::{Ipv4Addr, SocketAddrV4, UdpSocket},
+    ptr::NonNull,
+};
 
 /// Creates a new instance of [UdpSocket].
 ///
@@ -62,7 +66,7 @@ pub unsafe extern "C" fn sp_udp_send_packet(
     unsafe { connection.as_ref().send(&Vec::from(packet)) }.is_ok()
 }
 
-/// Sends a [TypedCommand] to the display using the [UdpSocket].
+/// Sends a [SPCommand] to the display using the [UdpSocket].
 ///
 /// The passed `command` gets consumed.
 ///