fix up documentation some more

6 files changed, 102 insertions, 55 deletions

diff --git a/client/cmd.h b/client/cmd.h
index eac9834..7fee700 100644
--- a/client/cmd.h
+++ b/client/cmd.h
@@ -61,6 +61,9 @@ cmd_handle_t cmd_exit;
 /**
  * \brief \c test command
  *
+ * \note This command is only available in builds of \c pbc compiled with the
+ * \c DEBUG flag
+ *
  * ```
  * (pbc) test
  * ```
@@ -96,6 +99,9 @@ cmd_handle_t cmd_reset;
 /**
  * \brief \c send command
  *
+ * \note This command is only available in builds of \c pbc compiled with the
+ * \c DEBUG flag
+ *
  * ```
  * (pbc) send <addr> <data>
  * ```
@@ -178,6 +184,15 @@ cmd_handle_t cmd_send;
 cmd_handle_t cmd_skip;
 /**
  * \brief \c dump command
+ *
+ * \note This command is only available in builds of \c pbc compiled with the
+ * \c DEBUG flag
+ *
+ * ```
+ * (pbc) dump <none|send|recv|both>
+ * ```
+ * 
+ * Show raw I2C messages being sent to/from the main controller.
  */
 cmd_handle_t cmd_dump;
 
diff --git a/client/readme.md b/client/readme.md
index d99991f..375e8c1 100644
--- a/client/readme.md
+++ b/client/readme.md
@@ -10,20 +10,24 @@ game operator to control and monitor the state of a puzzle box, but is also a
 useful debugging tool when developing puzzle modules, as it allows you to send
 arbitrary data over the puzzle bus.
 
+> [!NOTE]
+> The client depends on the [GNU readline][readline] library, which is not
+> included as a submodule because it is installed on most Linux distributions
+> by default. Please ensure you have the readline development headers installed
+> for your distribution of choice.
+
 ## Features
 
-- List detected puzzle modules
-- Reset puzzle modules (individually or all to reset the box)
-- Skip puzzle modules (individually or all)
-- Request puzzle box state
+- Individually reset puzzle modules
+- Individually skip puzzle modules
 - Debug: send arbitrary messages
 
 ## Usage
 
-See \ref pbc_cmd_usage "command usage" for individual command usage.
+See [command usage](#pbc_cmd_usage)
 
-## WIP TODO
+## Bugs
 
-- add enum to string functions in CLIENT ONLY
-- bug: tab completion for `dump` seems to print garbage sometimes
+- tab completion for the `dump` command seems to print garbage (sometimes)
 
+[readline]: https://www.gnu.org/software/readline
diff --git a/lib/pbdrv/index.dox b/lib/pbdrv/index.dox
index 0be5f33..03a17b5 100644
--- a/lib/pbdrv/index.dox
+++ b/lib/pbdrv/index.dox
@@ -30,10 +30,9 @@ target_link_libraries(main pbdrv)
 
 pbdrv-mod is a superset of \ref pbdrv, and includes functions specific to
 puzzle bus modules. \ref pbdrv-mod compiles to an object file instead of a
-static library because it may depend on functions that rely on external
-libraries. \ref pbdrv-mod is still considered standalone, but requires either
-using an existing \ref pb_drv "driver", or (partially) implementing the driver
-functions.
+static library because it may depend on functions from external libraries. \ref
+pbdrv-mod is still considered standalone, but requires either using an existing
+\ref pb_drv "driver", or (partially) implementing the driver functions.
 
 Like \ref pbdrv, \ref pbdrv-mod can be used by including this folder in your
 CMakeLists.txt file and linking the library with your executable. Please see
diff --git a/main/readme.md b/main/readme.md
index 97150eb..2a50fd1 100644
--- a/main/readme.md
+++ b/main/readme.md
@@ -4,17 +4,18 @@
 # main controller firmware
 
 This directory contains the software for the main controller of the Puzzle Box.
+The main controller target is a Raspberry Pi Pico W.
 
-## building
+## Building
 
-1. make sure the submodules are initialized
-2. create a `config.h` file (see \ref main_config "config")
-3. use CMake to build
+1. Create a `config.h` file (see [config](#main_config))
+2. Use CMake to build
 
-## flashing
+## Flashing
 
-1. build
-2. hold the BOOTSEL button while resetting the pico (by power cycling or
+1. Hold the BOOTSEL button while resetting the Pico (by power cycling or
    pulling pin 30 (RUN) to GND)
-3. `picotool load build/main.uf2`
+2. ```
+   $ picotool load build/main.uf2
+   ```
 
diff --git a/puzzle/readme.md b/puzzle/readme.md
index 1b572ba..833723e 100644
--- a/puzzle/readme.md
+++ b/puzzle/readme.md
@@ -15,7 +15,15 @@ sure you have done the following:
 - Open "Tools" > "Board" > "Board manager"
 - Install the "Arduino AVR Boards" package (1.8.6 works at the time of writing)
 
-[arduino-cmake]: https://github.com/a9183756-gh/Arduino-CMake-Toolchain
+Some puzzle modules also require installing libraries through the Arduino
+library manager. Dependencies for specific puzzle modules are detailed on their
+Doxygen pages.
+
+### Flashing
+
+```
+$ ninja -C build upload
+```
 
 <!--
 
@@ -33,3 +41,4 @@ sure you have done the following:
 
 -->
 
+[arduino-cmake]: https://github.com/a9183756-gh/Arduino-CMake-Toolchain
diff --git a/readme.md b/readme.md
index 5f71788..8a8a176 100644
--- a/readme.md
+++ b/readme.md
@@ -10,14 +10,58 @@ microcontrollers, and a recommendation is made in the [design
 document](docs/design.adoc). Please see the [handover
 document](docs/handover.adoc) first for more details.
 
+## Libraries
+
+Libraries are stored in the [lib](lib/) folder, and this folder is symlinked to
+from each subfolder in the project for convenience (allows CMake to include
+out-of-tree modules). The lib folder contains a mix of direct Git submodules
+and custom libraries specific to this project. (Most) external dependencies are
+tracked as git submodules, exceptions are in the [puzzle](puzzle/) folder.
+
+> [!NOTE]
+> Please note that symbolic links may not work correctly if you clone the
+> repository under a filesystem or operating system that does not support
+> these. MinGW/Windows are known to have issues with symlinks, so please verify
+> symlinks are recognised as such before attempting to build or initialize the
+> submodules.
+
+TL;DR: If something is complaining about missing files
+
+```
+git submodule update --init --recursive --depth 1
+```
+
+until your problems go away.
+
+## Building
+
+All subfolders/modules/libraries use CMake, and build in roughly the same way.
+All documentation assumes CMake is used in combination with Ninja, though other
+generators may also work. The following commands can be used inside each
+subfolder to compile (make sure you have initialized the submodules before
+compiling):
+
+```
+$ cmake -B build -G Ninja
+$ ninja -C build
+```
+
+Target-specific flashing/uploading commands are detailed in the respective
+folder's README.
+
 > [!NOTE]
-> This project was mostly developed on Linux. All subfolders/modules/libraries
-> use CMake, and *should* build cross-platform when using CMake+Ninja. This has
-> not yet been verified.
->
-> Please note that most subfolders use symbolic links to the [lib](lib/)
-> folder, which may not work correctly if you clone the repository under a
-> filesystem or operating system that does not support these.
+> Cross-platform compilation should be supported, though this has not been
+> verified. Most of this project was developed on Linux, and Windows
+> compatibility has not been verified.
+
+### lazy\.mk
+
+[`lazy.mk`](./lazy.mk) is a file made by Loek, and includes some rules for
+forwarding `make` calls to `cmake` and `ninja`. **This is purely for
+convenience, and should not become an essential part of the build system**.
+This file should be included at the end of a regular makefile. Any targets
+defined in a makefile can be used as-is, while targets that would otherwise be
+unknown will be forwarded to Ninja.
 
 ## Documentation
 
@@ -43,35 +87,10 @@ Please keep this repository tidy by being aware of the following conventions:
 - An `.editorconfig` file is provided in this repository. Please install the
   [EditorConfig](https://editorconfig.org/) plugin for your text editor of
   choice to automatically use these.
-- There are also `.clang-tidy` and `.clang-format` files, which can be enforced
-  by running
+- There are also `.clang-tidy` and `.clang-format` files which define specific
+  code style attributes. These can be enforced by running
 
   ```
   $ make format
   ```
 
-## Libraries
-
-Libraries are stored in the [lib](lib/) folder, and this folder is symlinked to
-from each subfolder in the project for convenience (allows CMake to include
-out-of-tree modules). The lib folder contains a mix of direct Git submodules
-and custom libraries specific to this project. (Most) external dependencies are
-tracked as git submodules, exceptions are in the [puzzle](puzzle/) folder.
-
-TL;DR: If something is complaining about missing files
-
-```
-git submodule update --init --recursive --depth 1
-```
-
-until your problems go away.
-
-## lazy\.mk
-
-[`lazy.mk`](./lazy.mk) is a file made by Loek, and includes some rules for
-forwarding `make` calls to `cmake` and `ninja`. **This is purely for
-convenience, and should not become an essential part of the build system**.
-This file should be included at the end of a regular makefile. Any targets
-defined in a makefile can be used as-is, while targets that would otherwise be
-unknown will be forwarded to Ninja.
-