From 2528775b34f9c0033027931385a4de866ab2749d Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Mon, 24 Jun 2024 08:31:35 +0200
Subject: add more documentation

---
 client/cmd.h      |  7 ++++++-
 client/i2c.h      |  2 +-
 client/parse.h    |  4 ++--
 client/sock.h     |  2 +-
 main/config.def.h | 27 ++++++++++++++++++++++++++-
 main/index.dox    |  6 +++---
 main/readme.md    | 12 +-----------
 7 files changed, 40 insertions(+), 20 deletions(-)

diff --git a/client/cmd.h b/client/cmd.h
index a3cc44a..4f77d50 100644
--- a/client/cmd.h
+++ b/client/cmd.h
@@ -2,8 +2,13 @@
 
 /**
  * \ingroup pbc
- * \defgroup pbc_cmd cmd
+ * \defgroup pbc_cmd Commands
  * \brief Commands within \ref pbc
+ *
+ * \note A manpage is available containing end-user usage instructions inside
+ * the \ref client folder in the source code repository. This page contains the
+ * internal code documentation for the commands defined in \c pbc.
+ *
  * \{
  */
 
diff --git a/client/i2c.h b/client/i2c.h
index 87f33c9..d2cfa9a 100644
--- a/client/i2c.h
+++ b/client/i2c.h
@@ -5,7 +5,7 @@
 
 /**
  * \ingroup pbc
- * \defgroup pbc_i2c i2c
+ * \defgroup pbc_i2c I2C
  * \brief I2C abstraction functions
  * \{
  */
diff --git a/client/parse.h b/client/parse.h
index 8b7d235..1beb714 100644
--- a/client/parse.h
+++ b/client/parse.h
@@ -4,8 +4,8 @@
 
 /**
  * \ingroup pbc
- * \defgroup pbc_parse parse
- * \brief Debug send command parser utilities
+ * \defgroup pbc_parse Parse
+ * \brief Debug \c send command parser utilities
  * \{
  */
 
diff --git a/client/sock.h b/client/sock.h
index c124e45..792123e 100644
--- a/client/sock.h
+++ b/client/sock.h
@@ -5,7 +5,7 @@
 
 /**
  * \ingroup pbc
- * \defgroup pbc_sock sock
+ * \defgroup pbc_sock Socket
  * \brief TCP socket handling
  * \{
  */
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
-- 
cgit v1.2.3