From bb63040692c94ffa662b0af7eb14f3c5951aa6e6 Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Sat, 22 Jun 2024 13:01:42 +0200
Subject: even more doxygen documentation

---
 lib/pbdrv/pb-serial.h | 76 +++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 65 insertions(+), 11 deletions(-)

(limited to 'lib/pbdrv/pb-serial.h')

diff --git a/lib/pbdrv/pb-serial.h b/lib/pbdrv/pb-serial.h
index d3d0007..79f08d7 100644
--- a/lib/pbdrv/pb-serial.h
+++ b/lib/pbdrv/pb-serial.h
@@ -8,23 +8,77 @@
 extern "C" {
 #endif
 
-#define __pb_cmd(name) \
-	pb_ser_r_t pb_ser_r_##name; \
-	pb_ser_w_t pb_ser_w_##name; \
-	pb_ser_free_t pb_ser_free_##name;
+/**
+ * \ingroup pbdrv
+ * \ingroup pbdrv-mod
+ * \defgroup pb_ser Serial
+ * \internal
+ * \brief Internal (de)serialization functions using mpack
+ *
+ * \{
+ */
 
+/**
+ * \brief Write (serialize) message fields using mpack
+ *
+ * \param writer Pointer to \c mpack_writer_t instance
+ * \param msg Pointer to message struct to read from
+ */
 typedef void pb_ser_w_t(mpack_writer_t * writer, const pb_msg_t * msg);
-pb_ser_w_t pb_ser_w;
-
+/**
+ * \brief Read (deserialize) message fields using mpack
+ *
+ * \param reader Pointer to \c mpack_reader_t instance
+ * \param msg Pointer to message struct to write to
+ */
 typedef void pb_ser_r_t(mpack_reader_t * reader, pb_msg_t * msg);
-pb_ser_r_t pb_ser_r;
-
+/**
+ * \brief Recursively free message struct fields
+ *
+ * \param msg Pointer to message struct to free
+ */
 typedef void pb_ser_free_t(pb_msg_t * msg);
+
+/**
+ * \brief Write the \ref pb_msg_t header fields and call another function for
+ * \p msg->cmd.
+ * \see pb_ser_w_t
+ */
+pb_ser_w_t pb_ser_w;
+/**
+ * \brief Read the \ref pb_msg_t header fields and call another function for \p
+ * msg->cmd.
+ * \see pb_ser_r_t
+ */
+pb_ser_r_t pb_ser_r;
+/**
+ * \brief Call another function for \p msg->cmd.
+ * \see pb_ser_free_t
+ */
 pb_ser_free_t pb_ser_free;
 
-__pb_cmd(cmd_prop)
-__pb_cmd(cmd_state)
-__pb_cmd(cmd_magic)
+//! Write the \ref pb_cmd_prop_t fields \see pb_ser_w_t
+pb_ser_w_t pb_ser_w_cmd_prop;
+//! Read the \ref pb_cmd_prop_t fields \see pb_ser_r_t
+pb_ser_r_t pb_ser_r_cmd_prop;
+//! Free the \ref pb_cmd_prop_t fields \see pb_ser_free_t
+pb_ser_free_t pb_ser_free_cmd_prop;
+
+//! Write the \ref pb_cmd_state_t fields \see pb_ser_w_t
+pb_ser_w_t pb_ser_w_cmd_state;
+//! Read the \ref pb_cmd_state_t fields \see pb_ser_r_t
+pb_ser_r_t pb_ser_r_cmd_state;
+//! Free the \ref pb_cmd_state_t fields \see pb_ser_free_t
+pb_ser_free_t pb_ser_free_cmd_state;
+
+//! Write the \ref pb_cmd_magic_t fields \see pb_ser_w_t
+pb_ser_w_t pb_ser_w_cmd_magic;
+//! Read the \ref pb_cmd_magic_t fields \see pb_ser_r_t
+pb_ser_r_t pb_ser_r_cmd_magic;
+//! Free the \ref pb_cmd_magic_t fields \see pb_ser_free_t
+pb_ser_free_t pb_ser_free_cmd_magic;
+
+/// \}
 
 #ifdef __cplusplus
 }
-- 
cgit v1.2.3