From 6d619ee8b5a5c2b6cf26362daf8cbaf9d2bb82a8 Mon Sep 17 00:00:00 2001
From: Daniel Barlow <dan@telent.net>
Date: Mon, 7 Aug 2023 21:43:12 +0100
Subject: [PATCH] add some missing descriptions

---
 modules/bridge/default.nix | 10 ++++++++++
 modules/hardware.nix       | 31 +++++++++++++++++++++++++++----
 2 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/modules/bridge/default.nix b/modules/bridge/default.nix
index 173a39c0..3fdfaf9a 100644
--- a/modules/bridge/default.nix
+++ b/modules/bridge/default.nix
@@ -1,3 +1,13 @@
+## Bridge module
+##
+##  Allows creation of Layer 2 software "bridge" network devices.  A
+##  common use case is to merge together a hardware Ethernet device
+##  with one or more WLANs so that several local devices appear to be
+##  on the same network. Create a ``primary`` service to specify the
+##  new device, and a ``members`` service to add constituent devices
+##  to it.
+
+
 { lib, pkgs, config, ...}:
 let
   inherit (lib) mkOption types;
diff --git a/modules/hardware.nix b/modules/hardware.nix
index d9852611..90040b75 100644
--- a/modules/hardware.nix
+++ b/modules/hardware.nix
@@ -7,13 +7,18 @@ in {
     };
     hardware = {
       dts = {
-        src = mkOption { type = types.path; };
+        src = mkOption {
+          type = types.path;
+          description = "Path to the device tree source (usually from OpenWrt)";
+        };
         includes = mkOption {
           default = [];
+          description = "List of directories to search for DTS includes (.dtsi files)";
           type = types.listOf types.path;
         };
       };
       defaultOutput = mkOption {
+        description = "\"Default\" output: what gets built for this device when outputs.default is requested. Typically this is \"flashimage\" or \"vmroot\"";
         type = types.nonEmptyStr;
       };
       flash = {
@@ -22,13 +27,31 @@ in {
         # kernel uimage and root fs. Not the entire flash, as
         # that often also contains the bootloader, data for
         # for wireless devices, etc
-        address = mkOption { type = types.str; };
-        size = mkOption { type = types.str; };
-        eraseBlockSize = mkOption { type = types.str; };
+        address = mkOption {
+          description = ''
+            Start address of whichever partition (often
+            called "firmware") we're going to overwrite with our
+            kernel uimage and root fs. Usually not the entire flash, as
+            we don't want to clobber the bootloader, calibration data etc
+          '';
+          type = types.str;
+        };
+        size = mkOption {
+          type = types.str;
+          description = "Size in bytes of the firmware partition";
+        };
+        eraseBlockSize = mkOption {
+          description = "Flash erase block size in bytes";
+          type = types.str;
+        };
       };
       loadAddress = mkOption { default = null; };
       entryPoint = mkOption { };
       radios = mkOption {
+        description = ''
+          Kernel modules (from mac80211 package) required for the
+          wireless devices on this board
+        '';
         type = types.listOf types.str;
         default = [];
         example = ["ath9k" "ath10k"];