WIP more documentation

5 files changed, 91 insertions, 19 deletions

diff --git a/.gitignore b/.gitignore
index 19dc4f4..6064624 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
 build
 .vscode/**
 .cache
+doxygen
diff --git a/Doxyfile b/Doxyfile
new file mode 100644
index 0000000..c3623cc
--- /dev/null
+++ b/Doxyfile
@@ -0,0 +1,21 @@
+# Doxyfile 1.11.0
+DOXYFILE_ENCODING = UTF-8
+PROJECT_NAME = "puzzlebox"
+OUTPUT_DIRECTORY = doxygen
+
+INPUT += client
+INPUT += lib/mpack
+INPUT += lib/i2ctcp
+INPUT += lib/pbdrv
+INPUT += main
+INPUT += puzzle/dummy
+
+EXCLUDE = lib/mpack/src
+EXCLUDE_PATTERNS = **/build
+EXCLUDE_SYMLINKS = YES
+
+FILE_PATTERNS = *.c *.cpp *.h *.hpp *.md
+RECURSIVE = YES
+
+GENERATE_LATEX = NO
+
diff --git a/docs/handover.adoc b/docs/handover.adoc
index 7bc52b3..c948b7b 100644
--- a/docs/handover.adoc
+++ b/docs/handover.adoc
@@ -120,11 +120,14 @@ which connects with the main controller to monitor/edit the game state. And the
 software for the puzzle modules 'Vault' and 'Neotrellis' is in the prototype state.
 
 == Incidents
-There were a multitude of different challenges we had to face before getting to a 
-working product. The majority of these have been documented here, and it is highly 
-recommended to have a look at this before development.
+
+During this year's run of the project, we encountered several difficuties we
+feel need to be addressed. We recommend that these incidents are analyzed by
+future project groups and incorporated into the risk analysis section of future
+project plan documents.
 
 === Misconceptions
+
 Make sure to know what you are developing and do some research beforehand, to make 
 sure you have the complete picture about what you are using. Sounds stupid, but it 
 happened for multiple project attempts, and caused time loss. This also includes 
@@ -133,6 +136,7 @@ and verify it on the lowest possible level for the same reason as previously
 mentioned.  
 
 === I^2^C
+
 I^2^C is easy to implement but also easy to underestimate, this project requires a 
 multi-master structure as communication is otherwise too complicated compared to 
 other means of communication.
@@ -149,24 +153,24 @@ been implemented to be able to continue using the RPI Pico W.
 To simplify; a controller is needed which supports multi-master 
 while being able to be addressed as a slave.
 
-=== Available Hardware/SDKs
-When choosing or using specific chips/SDKs make sure it is available for (at least) 
-a few years. This makes it easier for the next project team to use the same chips/SDKs
-instead of having to find new ones. This also includes having enough development boards 
-for multiple people to program using the same setup, e.g. the RPI Pico W requires 
-another RPI Pico W to be debugged. Effectively requiring the project team to have at 
-least 4 RPI Pico Ws to be able to develop in the same environment (if there are 2 
-software students).
+=== Development hardware availability
 
-=== Arduino
-Allocating memory using 'realloc' on Arduino is not possible, which makes it impossible 
-to use the 'mpack_writer_init_growable'.
+When choosing or using specific chips or development boards, make sure to
+include research on the product lifecycle. Choosing boards/chips that have
+planned long term support makes it easier for the next project team to order
+and use the same chips/boards instead of having to find new ones.
 
-=== Garbage workarounds
+This also includes having enough development boards for multiple people to
+program using the same setup, e.g. the RPI Pico W requires another RPI Pico W
+to be debugged, effectively requiring the project team to have at least 4 RPI
+Pico Ws to be able to develop in the same environment (if there are 2 software
+students).
+
+=== Auxiliary workarounds and technical limitations
 
 This section details unelegant workarounds that should be removed from the
-code. All workarounds are marked with ``FIXME:`` comments referring to one of
-the workarounds mentioned in this section.
+code. Workarounds that should be removed are marked with ``FIXME:`` comments
+referring to one of the workarounds mentioned in this section.
 
 RP2040 I^2^C limitations::
 - All puzzle module drivers have a hard-coded 2 second delay between receiving
@@ -174,6 +178,15 @@ RP2040 I^2^C limitations::
 	was done to ensure responses are not ignored by the RP2040 (main controller)
 	while it is still in I^2^C master mode.
 
+Memory management on Arduino::
+The Arduino's built-in memory management functions do not seem to work
+properly. The FreeRTOS heap 4 memory management functions are used on the
+puzzle modules instead. FreeRTOS does not have an implementation of the
+``realloc()`` function.
+- mpack's writer API cannot be used with a writer initialized using the
+	``mpack_writer_init_growable`` function on Arduino-based puzzle modules. The
+	``mpack_writer_init`` function is used with a static size buffer instead.
+
 == Recommendations
 
 === Imperatives
diff --git a/lib/pbdrv/pb-mod.h b/lib/pbdrv/pb-mod.h
index ae36d22..c4629a6 100644
--- a/lib/pbdrv/pb-mod.h
+++ b/lib/pbdrv/pb-mod.h
@@ -3,8 +3,8 @@
 /**
  * \file puzzle bus driver implementation
  *
- * Most \c pb_* functions have a weak implementation, which may be
- * overwritten by a custom implementation. This allows you to use the default
+ * Most \c pb_* functions have a weak implementation, which may be overwritten
+ * by a custom implementation. This allows you to use the default
  * implementation where possible, and only implement extensions required for
  * your puzzle module. Please see spec.adoc for more information about how to
  * use the puzzle bus driver library.
@@ -21,10 +21,42 @@ extern const char * PB_MOD_NAME;
 //! puzzle module bus address (required)
 extern const i2c_addr_t PB_MOD_ADDR;
 
+/**
+ * \brief handle a received message from the I2C bus (puzzle bus)
+ *
+ * This function attempts to parse an I2C message as a puzzle bus message, and
+ * calls the appropriate handler for the message if it is considered valid.
+ *
+ * \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
+ * FreeRTOS's \c xTimerPendFunctionCallFromISR() or a similar scheduler-based
+ * deferred function call mechanism instead.
+ */
 void pb_i2c_recv(const uint8_t * buf, size_t sz);
+/**
+ * \brief send a message in master-mode on the I2C bus (puzzle bus)
+ *
+ * This function sends an I2C message to the address specified by \p i2c_addr.
+ *
+ * \param i2c_addr address of slave controller
+ * \param buf pointer to message content
+ * \param sz size of \p buf
+ */
 void pb_i2c_send(i2c_addr_t i2c_addr, const uint8_t * buf, size_t sz);
 
+/**
+ * \brief global state read hook
+ * \ingroup hook
+ * \return current value of global state enum
+ */
 pb_global_state_t pb_hook_mod_state_read();
+/**
+ * \brief global state write hook
+ * \ingroup hook
+ * \param state new value of global state enum
+ */
 void pb_hook_mod_state_write(pb_global_state_t state);
 
 /**
diff --git a/makefile b/makefile
new file mode 100644
index 0000000..5f5340b
--- /dev/null
+++ b/makefile
@@ -0,0 +1,5 @@
+all: doxygen
+
+doxygen: Doxyfile
+	doxygen
+