no more undocumented things

6 files changed, 37 insertions, 24 deletions

diff --git a/lib/pbdrv/drv/arduino/mod.cpp b/lib/pbdrv/drv/arduino/mod.cpp
index 581b80a..81735af 100644
--- a/lib/pbdrv/drv/arduino/mod.cpp
+++ b/lib/pbdrv/drv/arduino/mod.cpp
@@ -47,11 +47,11 @@ static void pb_setup() {
  * with 2 Uno's, but ran into issues while integrating the Arduino's with the
  * RP2040.
  */
-__weak void pb_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz) {
-	if (pb_hook_i2c_send(addr, buf, sz)) return;
+__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;
 
 	vTaskDelay(10 / portTICK_PERIOD_MS); // prevent bus collisions
-	Wire.beginTransmission((int) addr);
+	Wire.beginTransmission((int) i2c_addr);
 	Wire.write(buf, sz);
 	Wire.endTransmission(true);
 	Wire.setWireTimeout(PB_TIMEOUT_US, true);
diff --git a/lib/pbdrv/drv/index.dox b/lib/pbdrv/drv/index.dox
index 89b9247..c0c1b76 100644
--- a/lib/pbdrv/drv/index.dox
+++ b/lib/pbdrv/drv/index.dox
@@ -8,12 +8,17 @@ Like \ref pb_ext "extensions", drivers provide platform-specific
 implementations for various functions used in \ref pbdrv-mod.
 
 If there is no existing driver for your target, you may implement the following
-in order to use \ref pbdrv-mod:
+in order to use \ref "pbdrv-mod":
 
 - The \c pb_i2c_recv() function must be **called** for every received I2C
 	message
 - The \c pb_i2c_send() function must be **implemented** using the
 	platform/device-specific I2C write function
+	\note The \c pb_i2c_send() function should immediately call \c
+	pb_hook_i2c_send() before doing any further processing:
+	```c
+	if (pb_hook_i2c_send(i2c_addr, buf, sz)) return;
+	```
 
 */
 
diff --git a/lib/pbdrv/index.dox b/lib/pbdrv/index.dox
index 8ddcb6a..0be5f33 100644
--- a/lib/pbdrv/index.dox
+++ b/lib/pbdrv/index.dox
@@ -68,6 +68,11 @@ extend or conditionally replace the default handlers), without needing to
 completely overwrite the built-in handlers or understand the internals of \ref
 pbdrv-mod.
 
+The boolean value returned by some hooks (e.g. those under \ref pb_hook_route
+or \ref pb_hook_i2c) represents if the default handler should run after the
+hook returns. This allow you to conditionally 'catch' calls to their respective
+base functions by returning \c true.
+
 \}
 
 */
diff --git a/lib/pbdrv/mod/main/pb-mod-main.h b/lib/pbdrv/mod/main/pb-mod-main.h
deleted file mode 100644
index 9c69c1d..0000000
--- a/lib/pbdrv/mod/main/pb-mod-main.h
+++ /dev/null
@@ -1,13 +0,0 @@
-#pragma once
-
-#include "../../pb-types.h"
-
-typedef struct {
-	i2c_addr_t mod_addr;
-	pb_global_state_t mod_state;
-} pb_mod_main_prop_mod_t;
-
-enum {
-	PB_MOD_MAIN_PROP_MODS = 0x00, //!< structured list of connected puzzle modules
-};
-
diff --git a/lib/pbdrv/pb-mod.h b/lib/pbdrv/pb-mod.h
index 7069b32..21e8100 100644
--- a/lib/pbdrv/pb-mod.h
+++ b/lib/pbdrv/pb-mod.h
@@ -75,16 +75,16 @@ void pb_i2c_send(i2c_addr_t i2c_addr, const uint8_t * buf, size_t sz);
  */
 
 /**
- * \brief global state read hook
- * \return current value of global state enum
+ * \brief Global state read hook
+ * \return Current value of global state enum
  *
  * The default implementation of this function uses an internal global state
  * variable in \ref pbdrv.
  */
 pb_global_state_t pb_hook_mod_state_read();
 /**
- * \brief global state write hook
- * \param state new value of global state enum
+ * \brief Global state write hook
+ * \param state New value of global state enum
  *
  * The default implementation of this function uses an internal global state
  * variable in \ref pbdrv.
@@ -101,7 +101,23 @@ void pb_hook_mod_state_write(pb_global_state_t state);
  * \{
  */
 
+/**
+ * \brief \c pb_i2c_recv() hook
+ *
+ * The default implementation of this function immediately returns \c false.
+ *
+ * \return \c false if execution should continue to the default handler, or \c
+ * true if it should stop (i.e. the message was handled).
+ */
 bool pb_hook_i2c_recv(const uint8_t * buf, size_t sz);
+/**
+ * \brief \c pb_i2c_send() hook
+ *
+ * The default implementation of this function immediately returns \c false.
+ *
+ * \return \c false if execution should continue to the default handler, or \c
+ * true if it should stop (i.e. the message was handled).
+ */
 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 2a28c0b..8b7bba5 100644
--- a/lib/pbdrv/pb-route.h
+++ b/lib/pbdrv/pb-route.h
@@ -140,10 +140,10 @@ void pb_route_cmd_magic_res(pb_msg_t * msg);
 /**
  * \brief \c pb_route_msg() hook
  *
- * The default implementation of this function immediately returns false.
+ * The default implementation of this function immediately returns \c false.
  *
- * \return \c true if execution should continue to the default handler, or \c
- * false if it should stop (i.e. the message was handled).
+ * \return \c false if execution should continue to the default handler, or \c
+ * true if it should stop (i.e. the message was handled).
  */
 bool pb_hook_route_msg(pb_msg_t * msg);