1 files changed, 167 insertions, 8 deletions

diff --git a/lib/pbdrv/pb-route.h b/lib/pbdrv/pb-route.h
index 41c009a..2a28c0b 100644
--- a/lib/pbdrv/pb-route.h
+++ b/lib/pbdrv/pb-route.h
@@ -6,31 +6,190 @@
 extern "C" {
 #endif
 
-void pb_route_msg(pb_msg_t * msg);
+/**
+ * \ingroup pbdrv-mod
+ * \defgroup pb_route Routing
+ * \internal
+ * \brief Parsed message handler routing
+ *
+ * These functions form a tree-shaped call graph, and are used to handle
+ * specific commands received from \c pb_i2c_recv().
+ *
+ * \{
+ */
 
-bool pb_hook_route_msg(pb_msg_t * msg);
+/**
+ * \brief Handle a message with type {\ref PB_CMD_PROP "PROP", \ref
+ * PB_CMD_STATE "STATE", \ref PB_CMD_MAGIC "MAGIC"}
+ *
+ * Calls the next handler depending on \c msg->type.
+ */
+void pb_route_msg(pb_msg_t * msg);
 
+/**
+ * \brief Handle a \ref PB_CMD_PROP "PROP" message with action {\ref
+ * pb_route_cmd_prop_req "REQ", \ref pb_route_cmd_prop_res "RES", \ref
+ * pb_route_cmd_prop_set "SET"}
+ *
+ * Calls the next handler depending on \c msg->action.
+ */
 void pb_route_cmd_prop(pb_msg_t * msg);
+/**
+ * \brief Handle a \ref PB_CMD_STATE "STATE" message with action {\ref
+ * pb_route_cmd_state_req "REQ", \ref pb_route_cmd_state_res "RES", \ref
+ * pb_route_cmd_state_set "SET"}
+ *
+ * Calls the next handler depending on \c msg->action.
+ */
 void pb_route_cmd_state(pb_msg_t * msg);
+/**
+ * \brief Handle a \ref PB_CMD_MAGIC "MAGIC" message with action {\ref
+ * pb_route_cmd_magic_req "REQ", \ref pb_route_cmd_magic_res "RES"}
+ *
+ * Calls the next handler depending on \c msg->action.
+ *
+ * \note Messages with type \c MAGIC and action \c SET will be silently
+ * ignored, as there is no such command.
+ */
 void pb_route_cmd_magic(pb_msg_t * msg);
 
-bool pb_hook_route_cmd_prop(pb_msg_t * msg);
-bool pb_hook_route_cmd_state(pb_msg_t * msg);
-bool pb_hook_route_cmd_magic(pb_msg_t * msg);
-
+/**
+ * \brief Handle a \ref PB_CMD_PROP "PROP" message with action \ref
+ * PB_ACTION_REQ "REQ"
+ *
+ * The default implementation of this function is empty, as puzzle module
+ * properties are user-defined.
+ */
 void pb_route_cmd_prop_req(pb_msg_t * msg);
+/**
+ * \brief Handle a \ref PB_CMD_PROP "PROP" message with action \ref
+ * PB_ACTION_RES "RES"
+ *
+ * The default implementation of this function is empty, as puzzle module
+ * properties are user-defined.
+ */
 void pb_route_cmd_prop_res(pb_msg_t * msg);
+/**
+ * \brief Handle a \ref PB_CMD_PROP "PROP" message with action \ref
+ * PB_ACTION_SET "SET"
+ *
+ * The default implementation of this function is empty, as puzzle module
+ * properties are user-defined.
+ */
 void pb_route_cmd_prop_set(pb_msg_t * msg);
 
+/**
+ * \brief Handle a \ref PB_CMD_STATE "STATE" message with action \ref
+ * PB_ACTION_REQ "REQ"
+ *
+ * The default implementation of this function does the following:
+ * - Call \c pb_hook_ev_module_init() if this is the first received \c STATE \c
+ *   REQ command.
+ * - Call \c pb_hook_ev_main_state_update() if the main controller state has
+ *   changed.
+ * - Reply with a \c STATE \c RES message.
+ */
 void pb_route_cmd_state_req(pb_msg_t * msg);
+/**
+ * \brief Handle a \ref PB_CMD_STATE "STATE" message with action \ref
+ * PB_ACTION_RES "RES"
+ *
+ * The default implementation of this function is empty, as only the main
+ * controller handles this type of command.
+ */
 void pb_route_cmd_state_res(pb_msg_t * msg);
+// TODO: add link to pb_route_cmd_state_res handler in main/i2c.c
+/**
+ * \brief Handle a \ref PB_CMD_STATE "STATE" message with action \ref
+ * PB_ACTION_SET "SET"
+ *
+ * The default implementation of this function does the following:
+ * - Write the global state variable using \c pb_hook_mod_state_write().
+ */
 void pb_route_cmd_state_set(pb_msg_t * msg);
 
-void pb_hook_main_state_update(pb_global_state_t state);
-
+/**
+ * \brief Handle a \ref PB_CMD_MAGIC "MAGIC" message with action \ref
+ * PB_ACTION_REQ "REQ"
+ *
+ * The default implementation of this function does the following:
+ * - Verify the size of the magic string
+ * - Verify the content of the magic string
+ * - Reply with a \c MAGIC \c RES message.
+ */
 void pb_route_cmd_magic_req(pb_msg_t * msg);
+/**
+ * \brief Handle a \ref PB_CMD_MAGIC "MAGIC" message with action \ref
+ * PB_ACTION_RES "RES"
+ *
+ * The default implementation of this function is empty, as only the main
+ * controller handles this type of command. (\ref main_route_cmd_magic_res
+ * "link")
+ */
 void pb_route_cmd_magic_res(pb_msg_t * msg);
 
+/// \}
+
+/**
+ * \ingroup pb_hook
+ * \defgroup pb_hook_route Routing
+ * \brief Conditionally use substitute or extend the built-in message handlers
+ * \{
+ */
+
+/**
+ * \brief \c pb_route_msg() hook
+ *
+ * The default implementation of this function immediately returns 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).
+ */
+bool pb_hook_route_msg(pb_msg_t * msg);
+
+//! \c pb_route_cmd_prop() hook \copydetails pb_hook_route_msg
+bool pb_hook_route_cmd_prop(pb_msg_t * msg);
+//! \c pb_route_cmd_state() hook \copydetails pb_hook_route_msg
+bool pb_hook_route_cmd_state(pb_msg_t * msg);
+//! \c pb_route_cmd_magic() hook \copydetails pb_hook_route_msg
+bool pb_hook_route_cmd_magic(pb_msg_t * msg);
+
+/// \}
+
+/**
+ * \ingroup pb_hook
+ * \defgroup pb_hook_ev Events
+ * \brief Functions called on puzzle bus-related events
+ * \{
+ */
+
+/**
+ * \brief Main controller state update hook
+ *
+ * The default implementation of this function is empty.
+ *
+ * \param state New state of main controller
+ *
+ * \note This function is also called when the first \c STATE \c REQ command is
+ * received, as the main controller state variable used to check if the state
+ * actually changed is initialized to \ref PB_GS_NOINIT. In this case, this
+ * function is called *after* \c pb_hook_ev_module_init().
+ */
+void pb_hook_ev_main_state_update(pb_global_state_t state);
+/**
+ * \brief Module initialized hook
+ *
+ * The default implementation of this function calls \c
+ * pb_hook_mod_state_write() with \ref PB_GS_IDLE.
+ *
+ * This function is called when the first \c STATE \c REQ command is received,
+ * indicating this puzzle module has been registered successfully by the main
+ * controller, and is now part of an active play session.
+ */
+void pb_hook_ev_module_init();
+
+/// \}
+
 #ifdef __cplusplus
 }
 #endif