add more cross-references and update old docs

3 files changed, 43 insertions, 11 deletions

diff --git a/lib/pbdrv/drv/arduino/mod.cpp b/lib/pbdrv/drv/arduino/mod.cpp
index 81735af..27237d2 100644
--- a/lib/pbdrv/drv/arduino/mod.cpp
+++ b/lib/pbdrv/drv/arduino/mod.cpp
@@ -40,12 +40,12 @@ static void pb_setup() {
 
 /**
  * \ingroup pb_drv_arduino
- * \warning This function includes a hard-coded 10ms delay before sending. This
- * is to work around a weird issue where the Arduino pulls both SDA and SCL low
- * while attempting to initiate an I2C transmission. We were able to verify
- * that the Arduino correctly handles bus arbitration under a test scenario
- * with 2 Uno's, but ran into issues while integrating the Arduino's with the
- * RP2040.
+ * \warning In the Arduino driver, this function includes a hard-coded 10ms
+ * delay before sending. This is to work around a weird issue where the Arduino
+ * pulls both SDA and SCL low while attempting to initiate an I2C transmission.
+ * We were able to verify that the Arduino correctly handles bus arbitration
+ * under a test scenario with 2 Uno's, but ran into issues while integrating
+ * the Arduino's with the RP2040.
  */
 __weak void pb_i2c_send(i2c_addr_t i2c_addr, const uint8_t * buf, size_t sz) {
 	if (pb_hook_i2c_send(i2c_addr, buf, sz)) return;
diff --git a/lib/pbdrv/pb-mod.h b/lib/pbdrv/pb-mod.h
index 21e8100..0050869 100644
--- a/lib/pbdrv/pb-mod.h
+++ b/lib/pbdrv/pb-mod.h
@@ -44,9 +44,13 @@ extern const i2c_addr_t PB_MOD_ADDR;
  * \param buf pointer to message content
  * \param sz size of \p buf
  *
- * \note This function should not be directly called from an ISR. Please use
+ * \see pb_hook_i2c_recv()
+ *
+ * \warning Some platforms produce weird behavior when replying directly from
+ * the I2C ISR. Please verify if this function can be called directly on your
+ * target platform when writing a new driver. If it does not work as expected,
  * FreeRTOS's \c xTimerPendFunctionCallFromISR() or a similar scheduler-based
- * deferred function call mechanism instead.
+ * deferred function call mechanism may be used as a workaround.
  */
 void pb_i2c_recv(const uint8_t * buf, size_t sz);
 /**
@@ -57,6 +61,8 @@ void pb_i2c_recv(const uint8_t * buf, size_t sz);
  * \param i2c_addr address of slave controller
  * \param buf pointer to message content
  * \param sz size of \p buf
+ *
+ * \see pb_hook_i2c_send()
  */
 void pb_i2c_send(i2c_addr_t i2c_addr, const uint8_t * buf, size_t sz);
 
@@ -108,6 +114,8 @@ void pb_hook_mod_state_write(pb_global_state_t state);
  *
  * \return \c false if execution should continue to the default handler, or \c
  * true if it should stop (i.e. the message was handled).
+ *
+ * \see pb_i2c_recv()
  */
 bool pb_hook_i2c_recv(const uint8_t * buf, size_t sz);
 /**
@@ -117,6 +125,8 @@ bool pb_hook_i2c_recv(const uint8_t * buf, size_t sz);
  *
  * \return \c false if execution should continue to the default handler, or \c
  * true if it should stop (i.e. the message was handled).
+ *
+ * \see pb_i2c_send()
  */
 bool pb_hook_i2c_send(i2c_addr_t i2c_addr, const uint8_t * buf, size_t sz);
 
diff --git a/lib/pbdrv/pb-route.h b/lib/pbdrv/pb-route.h
index 8b7bba5..5c28f4d 100644
--- a/lib/pbdrv/pb-route.h
+++ b/lib/pbdrv/pb-route.h
@@ -23,6 +23,8 @@ extern "C" {
  * PB_CMD_STATE "STATE", \ref PB_CMD_MAGIC "MAGIC"}
  *
  * Calls the next handler depending on \c msg->type.
+ *
+ * \see pb_hook_route_msg()
  */
 void pb_route_msg(pb_msg_t * msg);
 
@@ -32,6 +34,8 @@ void pb_route_msg(pb_msg_t * msg);
  * pb_route_cmd_prop_set "SET"}
  *
  * Calls the next handler depending on \c msg->action.
+ *
+ * \see pb_hook_route_cmd_prop()
  */
 void pb_route_cmd_prop(pb_msg_t * msg);
 /**
@@ -40,6 +44,8 @@ void pb_route_cmd_prop(pb_msg_t * msg);
  * pb_route_cmd_state_set "SET"}
  *
  * Calls the next handler depending on \c msg->action.
+ *
+ * \see pb_hook_route_cmd_state()
  */
 void pb_route_cmd_state(pb_msg_t * msg);
 /**
@@ -50,6 +56,8 @@ void pb_route_cmd_state(pb_msg_t * msg);
  *
  * \note Messages with type \c MAGIC and action \c SET will be silently
  * ignored, as there is no such command.
+ *
+ * \see pb_hook_route_cmd_magic()
  */
 void pb_route_cmd_magic(pb_msg_t * msg);
 
@@ -144,14 +152,28 @@ void pb_route_cmd_magic_res(pb_msg_t * msg);
  *
  * \return \c false if execution should continue to the default handler, or \c
  * true if it should stop (i.e. the message was handled).
+ *
+ * \see pb_route_msg()
  */
 bool pb_hook_route_msg(pb_msg_t * msg);
 
-//! \c pb_route_cmd_prop() hook \copydetails pb_hook_route_msg
+/**
+ * \brief \c pb_route_cmd_prop() hook
+ * \copydetails pb_hook_route_msg
+ * \see pb_route_cmd_prop()
+ */
 bool pb_hook_route_cmd_prop(pb_msg_t * msg);
-//! \c pb_route_cmd_state() hook \copydetails pb_hook_route_msg
+/**
+ * \brief \c pb_route_cmd_state() hook
+ * \copydetails pb_hook_route_msg
+ * \see pb_route_cmd_state()
+ */
 bool pb_hook_route_cmd_state(pb_msg_t * msg);
-//! \c pb_route_cmd_magic() hook \copydetails pb_hook_route_msg
+/**
+ * \brief \c pb_route_cmd_magic() hook
+ * \copydetails pb_hook_route_msg
+ * \see pb_route_cmd_magic()
+ */
 bool pb_hook_route_cmd_magic(pb_msg_t * msg);
 
 /// \}