From c9c51dcdc2d94cd47af06ae68a5ae7707ca74b1b Mon Sep 17 00:00:00 2001
From: Vinzenz Schroeter <vinzenz.f.s@gmail.com>
Date: Thu, 29 Aug 2024 22:02:53 +0200
Subject: [PATCH] improve doc comments

---
 .../examples/lang_c/include/servicepoint.h    | 41 ++++---------------
 crates/servicepoint_binding_c/src/bit_vec.rs  |  2 +-
 crates/servicepoint_binding_c/src/command.rs  |  6 ++-
 3 files changed, 13 insertions(+), 36 deletions(-)

diff --git a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h
index 5fb4334..d2f69b1 100644
--- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h
+++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h
@@ -128,7 +128,7 @@ typedef uint16_t sp_CompressionCode;
 typedef struct sp_Brightness sp_Brightness;
 
 /**
- * Opaque struct needed for correct code generation.
+ * A vector of bits
  */
 typedef struct sp_CBitVec sp_CBitVec;
 
@@ -138,7 +138,11 @@ typedef struct sp_CBitVec sp_CBitVec;
 typedef struct sp_CBrightnessGrid sp_CBrightnessGrid;
 
 /**
- * Opaque struct needed for correct code generation.
+ * A low-level display command.
+ *
+ * This struct and associated functions implement the UDP protocol for the display.
+ *
+ * To send a `CCommand`, use a `Connection`.
  */
 typedef struct sp_CCommand sp_CCommand;
 
@@ -149,37 +153,6 @@ typedef struct sp_CCommand sp_CCommand;
  */
 typedef struct sp_CCp437Grid sp_CCp437Grid;
 
-/**
- * A low-level display command.
- *
- * This struct and associated functions implement the UDP protocol for the display.
- *
- * To send a `Command`, use a `Connection`.
- *
- * # Examples
- *
- * ```rust
- * # use servicepoint::{Brightness, Command, Connection, Packet};
- *
- * // create command
- * let command = Command::Brightness(Brightness::MAX);
- *
- * // turn command into Packet
- * let packet: Packet = command.clone().into();
- *
- * // read command from packet
- * let round_tripped = Command::try_from(packet).unwrap();
- *
- * // round tripping produces exact copy
- * assert_eq!(command, round_tripped);
- *
- * // send command
- * # let connection = Connection::open("127.0.0.1:2342").unwrap();
- * connection.send(command).unwrap();
- * ```
- */
-typedef struct sp_Command sp_Command;
-
 /**
  * A connection to the display.
  *
@@ -1046,7 +1019,7 @@ void sp_packet_dealloc(struct sp_Packet *this_);
  * - the returned `Packet` instance is freed in some way, either by using a consuming function or
  *   by explicitly calling `sp_packet_dealloc`.
  */
-struct sp_Packet *sp_packet_from_command(struct sp_Command *command);
+struct sp_Packet *sp_packet_from_command(struct sp_CCommand *command);
 
 /**
  * Tries to load a `Packet` from the passed array with the specified length.
diff --git a/crates/servicepoint_binding_c/src/bit_vec.rs b/crates/servicepoint_binding_c/src/bit_vec.rs
index e930dbc..73aeefb 100644
--- a/crates/servicepoint_binding_c/src/bit_vec.rs
+++ b/crates/servicepoint_binding_c/src/bit_vec.rs
@@ -8,7 +8,7 @@ use servicepoint::bitvec::prelude::{BitVec, Msb0};
 /// cbindgen:no-export
 type SpBitVec = BitVec<u8, Msb0>;
 
-/// Opaque struct needed for correct code generation.
+/// A vector of bits
 #[derive(Clone)]
 pub struct CBitVec {
     actual: SpBitVec,
diff --git a/crates/servicepoint_binding_c/src/command.rs b/crates/servicepoint_binding_c/src/command.rs
index 2e2bc7e..3a34bcf 100644
--- a/crates/servicepoint_binding_c/src/command.rs
+++ b/crates/servicepoint_binding_c/src/command.rs
@@ -12,7 +12,11 @@ use crate::bit_vec::CBitVec;
 use crate::brightness_grid::CBrightnessGrid;
 use crate::cp437_grid::CCp437Grid;
 
-/// Opaque struct needed for correct code generation.
+/// A low-level display command.
+///
+/// This struct and associated functions implement the UDP protocol for the display.
+///
+/// To send a `CCommand`, use a `Connection`.
 pub struct CCommand(pub(crate) Command);
 
 impl Clone for CCommand {