docs done

7 files changed, 97 insertions, 25 deletions

diff --git a/main/blink.h b/main/blink.h
index 51c5f32..f8262d0 100644
--- a/main/blink.h
+++ b/main/blink.h
@@ -1,4 +1,16 @@
 #pragma once
 
+/**
+ * \ingroup main_tasks
+ * \{
+ */
+
+/**
+ * \brief Status LED blink task
+ *
+ * This task is started after initialization is complete, and blinks the
+ * on-board LED to indicate the Pico has completed initialization successfully.
+ */
 void blink_task();
 
+/// \}
diff --git a/main/config.def.h b/main/config.def.h
index e9503ed..0dae608 100644
--- a/main/config.def.h
+++ b/main/config.def.h
@@ -3,31 +3,44 @@
 #include <cyw43_country.h>
 
 /**
+ * \ingroup main
+ * \defgroup main_config config
+ * \brief Configuration options
+ * \{
+ */
+
+/**
  * \name Network (Wi-Fi) configuration
  * \{
  */
 #ifndef CFG_NET_SSID
-//! network name (SSID)
+/**
+ * \brief Network name (SSID)
+ * \note Not defining \c CFG_NET_SSID will implicitly enable \c CFG_NET_DISABLE
+ */
 #define CFG_NET_SSID ""
 #ifndef CFG_NET_DISABLE
-//! disable network communication
+/**
+ * \brief Disable network communication completely
+ * \note Enabling this option will implicitly enable \c CFG_SRV_DISABLE
+ */
 #define CFG_NET_DISABLE
 #warning No SSID defined! Disabling network communication!
 #endif
 #endif
 
 #ifndef CFG_NET_PASS
-//! network password
+//! Network password
 #define CFG_NET_PASS ""
 #endif
 
 #ifndef CFG_NET_AUTH
-//! network security type
+//! Network security type
 #define CFG_NET_AUTH CYW43_AUTH_OPEN
 #endif
 
 #ifndef CFG_NET_CONN_TIMEOUT
-//! max duration (milliseconds) for establishing wifi connection
+//! Max duration (milliseconds) for establishing Wi-Fi connection
 #define CFG_NET_CONN_TIMEOUT 10e3
 #endif
 
@@ -36,47 +49,52 @@
 #define CFG_NET_COUNTRY CYW43_COUNTRY_WORLDWIDE
 #endif
 #ifndef CFG_NET_COUNTRY
-//! radio communications country
+//! Radio communications country
 #define CFG_NET_COUNTRY CYW43_COUNTRY_NETHERLANDS
 #endif
-/** \} */
+/// \}
 
 /**
- * \name i2ctcp server configuration
+ * \name TCP server configuration
  * \{
  */
 #ifndef CFG_SRV_PORT
-//! i2ctcp server port
+//! TCP server port
 #define CFG_SRV_PORT 9191
 #endif
-
 #ifdef CFG_NET_DISABLE
-//! disable the i2ctcp server
+//! Disable the TCP server
 #define CFG_SRV_DISABLE
 #endif
-/** \} */
+/// \}
 
 /**
  * \name I2C configuration
  * \{
  */
 #ifndef CFG_SDA_PIN
-//! I^2^C SDA pin
+//! I2C SDA pin
 #define CFG_SDA_PIN 16
 #endif
 #ifndef CFG_SCL_PIN
-//! I^2^C SCL pin
+//! I2C SCL pin
 #define CFG_SCL_PIN 17
 #endif
-/** \} */
+/// \}
 
+/**
+ * \name Auxiliary options
+ * \{
+ */
 #ifndef CFG_LED_PIN
-//! status LED pin
+//! Status LED pin
 #define CFG_LED_PIN CYW43_WL_GPIO_LED_PIN
 #endif
-
 #ifndef CFG_PB_MOD_MAX
-//! maximum number of simultaniously connected puzzle modules
+//! Maximum number of simultaniously connected puzzle modules
 #define CFG_PB_MOD_MAX 8
 #endif
+/// \}
+
+/// \}
 
diff --git a/main/i2c.h b/main/i2c.h
index d1173c8..107a04d 100644
--- a/main/i2c.h
+++ b/main/i2c.h
@@ -1,5 +1,17 @@
 #pragma once
 
-//! looking for slave addresses and requesting updates
+/**
+ * \ingroup main_tasks
+ * \{
+ */
+
+/**
+ * \brief I2C bus activity task 
+ *
+ * This function does an initial bus scan for puzzle modules, and then goes
+ * into an infinite loop that periodically polls all puzzle modules for their
+ * global state.
+ */
 void bus_task();
 
+/// \}
diff --git a/main/index.dox b/main/index.dox
new file mode 100644
index 0000000..aa2d07a
--- /dev/null
+++ b/main/index.dox
@@ -0,0 +1,6 @@
+// vim:ft=doxygen
+/**
+\ingroup main
+\defgroup main_tasks tasks
+\brief Tasks
+*/
diff --git a/main/init.h b/main/init.h
index 73d2773..a24977d 100644
--- a/main/init.h
+++ b/main/init.h
@@ -1,11 +1,17 @@
 #pragma once
 
 /**
- * \brief initialize the main controller
+ * \ingroup main
+ * \{
+ */
+
+/**
+ * \brief Initialize the main controller
  *
  * This function only synchronously initializes the standard input/output (used
- * for `printf` and `panic`), and queues all other types of initialization in
- * the `init` task using FreeRTOS.
+ * for \c printf() and \c panic()), and queues all other types of
+ * initialization in the \c async_init() task using FreeRTOS.
  */
 void init();
 
+/// \}
diff --git a/main/sock.h b/main/sock.h
index 38fca01..a151973 100644
--- a/main/sock.h
+++ b/main/sock.h
@@ -1,8 +1,17 @@
 #pragma once
 
-#include <stdint.h>
-#include <stddef.h>
+/**
+ * \ingroup main_tasks
+ * \{
+ */
 
-//! start listening for TCP socket requests
+/**
+ * \brief Listen for TCP socket messages
+ *
+ * This task starts a TCP server that listens for messages using \ref i2ctcp,
+ * and sends any received I2C messages (also using \ref i2ctcp).
+ */
 void serve_task();
 
+/// \}
+
diff --git a/main/tasks.h b/main/tasks.h
index 002f830..ac77a9e 100644
--- a/main/tasks.h
+++ b/main/tasks.h
@@ -1,4 +1,13 @@
 #pragma once
 
+/**
+ * \ingroup main
+ * \{
+ */
+
+/**
+ * \brief Register \ref main_tasks "all tasks" in FreeRTOS
+ */
 void init_tasks();
 
+/// \}