add more documentation

3 files changed, 30 insertions, 15 deletions

diff --git a/main/config.def.h b/main/config.def.h
index b3be5ed..cb6e8b4 100644
--- a/main/config.def.h
+++ b/main/config.def.h
@@ -4,8 +4,33 @@
 
 /**
  * \ingroup main
- * \defgroup main_config config
+ * \defgroup main_config Config
  * \brief Configuration options
+ *
+ * The main controller firmware is configured statically (i.e. through
+ * compile-time defined options). Because the configuration is likely to
+ * contain Wi-Fi credentials, this file is not tracked under version control.
+ *
+ * Before compiling the main controller fimrware, a file (`config.h`) must be
+ * created by the user with the following format:
+ *
+ * ```c
+ * #pragma once
+ *
+ * // define non-default options here
+ *
+ * #include "config.def.h"
+ * ```
+ *
+ * \note `config.def.h` contains preprocessor logic that tries to ensure a
+ * correct configuration. The default configuration has the following settings:
+ * - Wi-Fi is disabled (prints a warning during compilation because it was not
+ *   explicitly disabled by the user)
+ * - The TCP server is disabled (due to Wi-Fi being disabled)
+ *
+ * \note The exact default values of each configuration option, and all
+ * available options are listed below.
+ *
  * \{
  */
 
diff --git a/main/index.dox b/main/index.dox
index 0fee58a..54c5b15 100644
--- a/main/index.dox
+++ b/main/index.dox
@@ -1,13 +1,13 @@
 // vim:ft=doxygen
 /**
 \ingroup main
-\defgroup main_tasks tasks
-\brief Tasks
+\defgroup main_tasks Tasks
+\brief FreeRTOS tasks
 */
 
 /**
 \ingroup main
-\defgroup main_pb_override overrides
+\defgroup main_pb_override Overrides
 \brief Override functions from \ref pbdrv-mod
 */
 
diff --git a/main/readme.md b/main/readme.md
index 85a3fca..97150eb 100644
--- a/main/readme.md
+++ b/main/readme.md
@@ -8,17 +8,7 @@ This directory contains the software for the main controller of the Puzzle Box.
 ## building
 
 1. make sure the submodules are initialized
-2. create a `config.h` file and define some options (see `config.def.h` for all
-   options):
-   ```c
-   #pragma once
-
-   #define CFG_NET_SSID "network name"
-   #define CFG_NET_PASS "network password"
-   #define CFG_NET_AUTH CYW43_AUTH_WPA2_AES_PSK
-
-   #include "config.def.h"
-   ```
+2. create a `config.h` file (see \ref main_config "config")
 3. use CMake to build
 
 ## flashing