From 2a29a00dfe4e7e775dc746687f646faf93ff5877 Mon Sep 17 00:00:00 2001
From: Daniel Barlow <dan@telent.net>
Date: Wed, 9 Aug 2023 22:27:37 +0100
Subject: [PATCH] much text, such doc, very wow

---
 modules/base.nix        |  4 ++++
 modules/busybox.nix     | 10 ++++++++++
 modules/hardware.nix    |  8 ++++++++
 modules/ppp/default.nix | 11 ++++++-----
 modules/users.nix       | 13 +++++++++++++
 5 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/modules/base.nix b/modules/base.nix
index 0c675b51..c6322e1f 100644
--- a/modules/base.nix
+++ b/modules/base.nix
@@ -1,3 +1,7 @@
+## Base options
+## ============
+
+
 { lib, pkgs, config, ...}:
 let
   inherit (lib) mkEnableOption mkOption types isDerivation hasAttr ;
diff --git a/modules/busybox.nix b/modules/busybox.nix
index 953c3103..8ca580ef 100644
--- a/modules/busybox.nix
+++ b/modules/busybox.nix
@@ -1,3 +1,11 @@
+## Busybox
+## =======
+##
+## Busybox provides stripped-down versions of many usual
+## Linux/Unix tools, and may be configured to include only
+## the commands (termed "applets") required by the user or
+## by other included modules.
+
 { lib, pkgs, config, ...}:
 let
   inherit (lib) mkOption mkEnableOption types mapAttrsToList;
@@ -47,12 +55,14 @@ in {
     programs.busybox = {
       applets =  mkOption {
         type = types.listOf types.str;
+        description = "Applets required";
         default = [];
         example = ["sh" "getty" "login"];
       };
       options = mkOption {
         # mostly the values are y n or m, but sometimes
         # other strings are also used
+        description = "Other busybox config flags that do not map directly to applet names (often prefixed FEATURE_)";
         type = types.attrsOf types.nonEmptyStr;
         default =  { };
       };
diff --git a/modules/hardware.nix b/modules/hardware.nix
index 90040b75..7ad33bcc 100644
--- a/modules/hardware.nix
+++ b/modules/hardware.nix
@@ -1,3 +1,11 @@
+## Hardware-dependent options
+## ==========================
+##
+## These are attributes of the hardware not of the application
+## you want to run on it, and would usually be set in the "device" file:
+## :file:`devices/manuf-model/default.nix`
+
+
 { lib, pkgs, config, ...}:
 let
   inherit (lib) mkEnableOption mkOption types isDerivation hasAttr ;
diff --git a/modules/ppp/default.nix b/modules/ppp/default.nix
index f6040b0d..baa7188e 100644
--- a/modules/ppp/default.nix
+++ b/modules/ppp/default.nix
@@ -1,11 +1,12 @@
 ## PPP
 ## ===
 ##
-## A rudimentary PPPoE (PPP over Ethernet) configuration to address
-## the case where your Liminix device is connected to an upstream
-## network using PPPoE. This is typical for UK broadband connections
-## (except "cable"), and common in some other localities as well: ask
-## your ISP if this is you.
+## A PPPoE (PPP over Ethernet) configuration to address the case where
+## your Liminix device is connected to an upstream network using
+## PPPoE. This is typical for UK broadband connections where the
+## physical connection is made by OpenReach ("Fibre To The X") and
+## common in some other localities as well: ask your ISP if this is
+## you.
 
 { lib, pkgs, config, ...}:
 let
diff --git a/modules/users.nix b/modules/users.nix
index 556e0428..dc03a97e 100644
--- a/modules/users.nix
+++ b/modules/users.nix
@@ -1,3 +1,16 @@
+## Users
+## =====
+##
+## User- and group-related configuration.
+##
+## Changes made here are reflected in files such as :file:/etc/shadow,
+## :file:/etc/passwd, :file:/etc/group etc. If you are familiar with
+## user configuration in NixOS, please note that Liminix does not have
+## the concept of "mutable users" - files in /etc/ are symlinks to
+## the immutable store, so you can't e.g  change a password with
+## :command:`passwd`
+
+
 { lib, pkgs, config, ...}:
 let
   inherit (lib)