more docs

5 files changed, 144 insertions, 31 deletions

diff --git a/lib/pbdrv/pb-buf.h b/lib/pbdrv/pb-buf.h
index 9ff53fe..8b4bb10 100644
--- a/lib/pbdrv/pb-buf.h
+++ b/lib/pbdrv/pb-buf.h
@@ -16,8 +16,8 @@ extern "C" {
 
 //! binary buffer struct
 typedef struct {
-	char * data; //! pointer to data
-	size_t size; //! size of data
+	char * data; //!< pointer to data
+	size_t size; //!< size of data
 } pb_buf_t;
 
 /**
diff --git a/lib/pbdrv/pb-mod.h b/lib/pbdrv/pb-mod.h
index ef2cd77..75fcbec 100644
--- a/lib/pbdrv/pb-mod.h
+++ b/lib/pbdrv/pb-mod.h
@@ -9,27 +9,26 @@ extern "C" {
 /**
  * \ingroup pbdrv-mod
  * \defgroup pb_mod Module
- * \brief Metadata and auxiliary utility functions
+ * \brief Puzzle module metadata and auxiliary utility functions
  * \{
  */
 
 /**
  * \brief Puzzle module name
- *
- * Optional to define, default value is "???"
+ * \note This constant is optional to define, its default value is "???"
  */
 extern const char * PB_MOD_NAME;
 /**
  * \brief Puzzle module bus address
- *
- * **Required** to define
+ * \warning This variable **must** be defined by the user
  */
 extern const i2c_addr_t PB_MOD_ADDR;
 
 /**
  * \brief Platform-specific blocking delay function
  *
- * FIXME: this should be removed (see handover: RP2040 I2C limitations)
+ * FIXME: this entire function should be removed (see handover: RP2040 I2C
+ * limitations)
  */
 void pb_mod_blocking_delay_ms(unsigned long ms);
 
diff --git a/lib/pbdrv/pb-send.c b/lib/pbdrv/pb-send.c
index 29d81ed..dc34c44 100644
--- a/lib/pbdrv/pb-send.c
+++ b/lib/pbdrv/pb-send.c
@@ -2,7 +2,7 @@
 #include "pb-mod.h"
 #include "pb-msg.h"
 
-__weak void pb_send_reply(pb_msg_t * msg, pb_buf_t * reply) {
+__weak void pb_send_reply(const pb_msg_t * msg, const pb_buf_t * reply) {
 	return pb_i2c_send(msg->sender, (uint8_t *) reply->data, reply->size);
 }
 
@@ -21,10 +21,10 @@ pb_buf_t pb_send_read_req(uint8_t propid) {
 	return pb_msg_write(&msg);
 }
 
-pb_buf_t pb_send_read_res(uint8_t propid, uint8_t * value, size_t size) {
+pb_buf_t pb_send_read_res(uint8_t propid, const uint8_t * value, size_t size) {
 	pb_cmd_prop_t cmd = {
 		.propid = propid,
-		.value = value,
+		.value = (uint8_t *) value,
 		._value_size = size,
 	};
 	pb_msg_t msg = {
@@ -36,10 +36,10 @@ pb_buf_t pb_send_read_res(uint8_t propid, uint8_t * value, size_t size) {
 	return pb_msg_write(&msg);
 }
 
-pb_buf_t pb_send_write_req(uint8_t propid, uint8_t * value, size_t size) {
+pb_buf_t pb_send_write_req(uint8_t propid, const uint8_t * value, size_t size) {
 	pb_cmd_prop_t cmd = {
 		.propid = propid,
-		.value = value,
+		.value = (uint8_t *) value,
 		._value_size = size,
 	};
 	pb_msg_t msg = {
diff --git a/lib/pbdrv/pb-send.h b/lib/pbdrv/pb-send.h
index 679df29..7e21eda 100644
--- a/lib/pbdrv/pb-send.h
+++ b/lib/pbdrv/pb-send.h
@@ -7,17 +7,126 @@
 extern "C" {
 #endif
 
-void pb_send_reply(pb_msg_t * msg, pb_buf_t * reply);
+/**
+ * \ingroup pbdrv-mod
+ * \defgroup pb_send Send
+ * \brief Functions for directly creating serialized message buffers
+ * \{
+ */
 
+/**
+ * \brief Utility function for replying to a message
+ *
+ * \param msg Message to reply to
+ * \param reply Data to send as reply
+ *
+ * This function uses \c pb_i2c_send() to send \p reply to \p msg->sender.
+ */
+void pb_send_reply(const pb_msg_t * msg, const pb_buf_t * reply);
+
+/**
+ * \brief Create a serialized \ref PB_CMD_PROP "PROP" \ref PB_ACTION_REQ "REQ"
+ * message
+ *
+ * \param propid Property ID to request
+ *
+ * \return Message buffer
+ *
+ * \note The buffer returned by this function must be free'd with \c
+ * pb_buf_free().
+ */
 pb_buf_t pb_send_read_req(uint8_t propid);
-pb_buf_t pb_send_read_res(uint8_t propid, uint8_t * value, size_t size);
-pb_buf_t pb_send_write_req(uint8_t propid, uint8_t * value, size_t size);
+/**
+ * \brief Create a serialized \ref PB_CMD_PROP "PROP" \ref PB_ACTION_RES "RES"
+ * message
+ *
+ * \param propid Requested property ID
+ * \param value Pointer to structured data in property
+ * \param size Size of \p value
+ *
+ * \return Message buffer
+ *
+ * \note The buffer returned by this function must be free'd with \c
+ * pb_buf_free().
+ */
+pb_buf_t pb_send_read_res(uint8_t propid, const uint8_t * value, size_t size);
+/**
+ * \brief Create a serialized \ref PB_CMD_PROP "PROP" \ref PB_ACTION_SET "SET"
+ * message
+ *
+ * \param propid Property ID to write
+ * \param value Pointer to data to write to property
+ * \param size Size of \p value
+ *
+ * \return Message buffer
+ *
+ * \note The buffer returned by this function must be free'd with \c
+ * pb_buf_free().
+ */
+pb_buf_t pb_send_write_req(uint8_t propid, const uint8_t * value, size_t size);
+/**
+ * \brief Create a serialized \ref PB_CMD_STATE "STATE" \ref PB_ACTION_REQ
+ * "REQ" message
+ *
+ * The current module's state is obtained using \c pb_hook_mod_state_read().
+ *
+ * \return Message buffer
+ *
+ * \note The buffer returned by this function must be free'd with \c
+ * pb_buf_free().
+ */
 pb_buf_t pb_send_state_req();
+/**
+ * \brief Create a serialized \ref PB_CMD_STATE "STATE" \ref PB_ACTION_RES
+ * "RES" message
+ *
+ * The current module's state is obtained using \c pb_hook_mod_state_read().
+ *
+ * \return Message buffer
+ *
+ * \note The buffer returned by this function must be free'd with \c
+ * pb_buf_free().
+ */
 pb_buf_t pb_send_state_res();
+/**
+ * \brief Create a serialized \ref PB_CMD_STATE "STATE" \ref PB_ACTION_SET
+ * "SET" message
+ *
+ * \param state Requested new state
+ *
+ * \return Message buffer
+ *
+ * \note The buffer returned by this function must be free'd with \c
+ * pb_buf_free().
+ */
 pb_buf_t pb_send_state_set(pb_global_state_t state);
+/**
+ * \brief Create a serialized \ref PB_CMD_MAGIC "MAGIC" \ref PB_ACTION_REQ
+ * "REQ" message
+ *
+ * The magic string is equal to \ref pb_cmd_magic_req.
+ *
+ * \return Message buffer
+ *
+ * \note The buffer returned by this function must be free'd with \c
+ * pb_buf_free().
+ */
 pb_buf_t pb_send_magic_req();
+/**
+ * \brief Create a serialized \ref PB_CMD_MAGIC "MAGIC" \ref PB_ACTION_RES
+ * "RES" message
+ *
+ * The magic string is equal to \ref pb_cmd_magic_res.
+ *
+ * \return Message buffer
+ *
+ * \note The buffer returned by this function must be free'd with \c
+ * pb_buf_free().
+ */
 pb_buf_t pb_send_magic_res();
 
+/// \}
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/pbdrv/pb-types.h b/lib/pbdrv/pb-types.h
index dfd5da9..ef3df54 100644
--- a/lib/pbdrv/pb-types.h
+++ b/lib/pbdrv/pb-types.h
@@ -18,19 +18,19 @@ extern "C" {
  */
 
 #ifdef __GNUC__
-//! Mark function as weak (allow user to override implementation)
 #define __weak __attribute__((weak))
 #endif
 #ifndef __weak
 #error Could not determine weak attribute for current compiler
+//! Mark function as weak (allow user to override implementation)
 #define __weak
 #endif
 
 //! I2C address (10 or 7 bit)
 typedef uint16_t i2c_addr_t;
 
-//! puzzle bus command types
-enum pb_cmd_id {
+//! Puzzle bus command types
+typedef enum {
 	/**
 	 * \brief puzzle module property (\ref pb_route_cmd_prop_req "REQ", \ref
 	 * pb_route_cmd_prop_res "RES", \ref pb_route_cmd_prop_set "SET")
@@ -60,29 +60,34 @@ enum pb_cmd_id {
 	 * unrelated I2C devices.
 	 */
 	PB_CMD_MAGIC,
-};
-typedef enum pb_cmd_id pb_cmd_id_t;
+} pb_cmd_id_t;
 
-//! puzzle bus command action types
-enum pb_action {
+//! Puzzle bus command action types
+typedef enum {
 	PB_ACTION_REQ, //!< request
 	PB_ACTION_RES, //!< response
 	PB_ACTION_SET, //!< (over)write
-};
-typedef enum pb_action pb_action_t;
+} pb_action_t;
 
-//! puzzle bus global states
-enum pb_global_state {
+//! Puzzle module global states
+typedef enum {
 	PB_GS_NOINIT, //!< uninitialized (only used by puzzle modules)
 	PB_GS_IDLE, //!< puzzle not started yet
 	PB_GS_PLAYING, //!< puzzle actively being solved
 	PB_GS_SOLVED, //!< puzzle completed
-};
-typedef enum pb_global_state pb_global_state_t;
+} pb_global_state_t;
 
-//! magic sent from main controller to puzzle module
+/**
+ * \brief Magic sent from main controller to puzzle module (="puzbus")
+ *
+ * The size of this array can be obtained by \c sizeof(pb_cmd_magic_req).
+ */
 static const char pb_cmd_magic_req[] = { 0x70, 0x75, 0x7a, 0x62, 0x75, 0x73 };
-//! magic reply from puzzle module back to main controller
+/**
+ * \brief Magic reply from puzzle module back to main controller (="gaming")
+ *
+ * The size of this array can be obtained by \c sizeof(pb_cmd_magic_res).
+ */
 static const char pb_cmd_magic_res[] = { 0x67, 0x61, 0x6d, 0x69, 0x6e, 0x67 };
 
 //! puzzle bus message header / container (shared by all commands)