diff --git a/modules/base.nix b/modules/base.nix
index 0c675b5..c6322e1 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 953c310..8ca580e 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 90040b7..7ad33bc 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 f6040b0..baa7188 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 556e042..dc03a97 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)