15 files changed, 111 insertions, 113 deletions

diff --git a/gnu/system/accounts.scm b/gnu/system/accounts.scm
index 52dbbbf3a33..de91efe669a 100644
--- a/gnu/system/accounts.scm
+++ b/gnu/system/accounts.scm
@@ -17,6 +17,14 @@
 ;;; You should have received a copy of the GNU General Public License
 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+;;;
+;;; Data structures representing user accounts and user groups.  This is meant
+;;; to be used both on the host side and at run time--e.g., in activation
+;;; snippets.
+;;;
+;;; Code:
+
 (define-module (gnu system accounts)
   #:use-module (guix records)
   #:use-module (ice-9 match)
@@ -55,15 +63,6 @@
 
             default-shell))
 
-
-;;; Commentary:
-;;;
-;;; Data structures representing user accounts and user groups.  This is meant
-;;; to be used both on the host side and at run time--e.g., in activation
-;;; snippets.
-;;;
-;;; Code:
-
 (define default-shell
   ;; Default shell for user accounts (a string or string-valued gexp).
   (make-parameter "/bin/sh"))
diff --git a/gnu/system/file-systems.scm b/gnu/system/file-systems.scm
index fd9065d2f6d..7ec2cd02594 100644
--- a/gnu/system/file-systems.scm
+++ b/gnu/system/file-systems.scm
@@ -21,6 +21,15 @@
 ;;; You should have received a copy of the GNU General Public License
 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+;;;
+;;; Declaring file systems to be mounted.
+;;;
+;;; Note: this file system is used both in the Shepherd and on the "host
+;;; side", so it must not include (gnu packages …) modules.
+;;;
+;;; Code:
+
 (define-module (gnu system file-systems)
   #:use-module (ice-9 match)
   #:use-module (rnrs bytevectors)
@@ -109,15 +118,6 @@
             swap-space-priority
             swap-space-discard?))
 
-;;; Commentary:
-;;;
-;;; Declaring file systems to be mounted.
-;;;
-;;; Note: this file system is used both in the Shepherd and on the "host
-;;; side", so it must not include (gnu packages …) modules.
-;;;
-;;; Code:
-
 (eval-when (expand load eval)
   (define invalid-file-system-flags
     ;; Note: Keep in sync with 'mount-flags->bit-mask'.
diff --git a/gnu/system/hurd.scm b/gnu/system/hurd.scm
index 4d5a3d6799b..b57526f93c2 100644
--- a/gnu/system/hurd.scm
+++ b/gnu/system/hurd.scm
@@ -17,6 +17,13 @@
 ;;; You should have received a copy of the GNU General Public License
 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+;;;
+;;; This module provides system-specifics for the GNU/Hurd operating system
+;;; and virtual machine.
+;;;
+;;; Code:
+
 (define-module (gnu system hurd)
   #:use-module (ice-9 match)
   #:use-module (guix gexp)
@@ -55,13 +62,6 @@
             %hurd-default-operating-system-kernel
             %setuid-programs/hurd))
 
-;;; Commentary:
-;;;
-;;; This module provides system-specifics for the GNU/Hurd operating system
-;;; and virtual machine.
-;;;
-;;; Code:
-
 (define %hurd-default-operating-system-kernel
   gnumach)
 
diff --git a/gnu/system/images/visionfive2.scm b/gnu/system/images/visionfive2.scm
index ee0682b6fcd..22f6545db12 100644
--- a/gnu/system/images/visionfive2.scm
+++ b/gnu/system/images/visionfive2.scm
@@ -17,6 +17,18 @@
 ;;; You should have received a copy of the GNU General Public License
 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+;;;
+;;;  With this image, VisionFive2 can boot from MMC1 (MicroSD card) with
+;;;  SDIO3.0 boot mode (RPIO_1:L, RGPIO_0:H -- see [1]), in this case the
+;;;  board will use U-Boot from Guix System instead of the vendor U-Boot.
+;;;  Booting from eMMC and NVME is still work-in-progress.
+;;;
+;;; References:
+;;;  1. <https://doc-en.rvspace.org/VisionFive2/Boot_UG/VisionFive2_SDK_QSG/boot_mode_settings.html>
+;;;
+;;; Code:
+
 (define-module (gnu system images visionfive2)
   #:use-module (gnu bootloader)
   #:use-module (gnu bootloader u-boot)
@@ -46,18 +58,6 @@
             visionfive2-image-type
             visionfive2-barebones-raw-image))
 
-;;; Commentary:
-;;;
-;;;  With this image, VisionFive2 can boot from MMC1 (MicroSD card) with
-;;;  SDIO3.0 boot mode (RPIO_1:L, RGPIO_0:H -- see [1]), in this case the
-;;;  board will use U-Boot from Guix System instead of the vendor U-Boot.
-;;;  Booting from eMMC and NVME is still work-in-progress.
-;;;
-;;; References:
-;;;  1. <https://doc-en.rvspace.org/VisionFive2/Boot_UG/VisionFive2_SDK_QSG/boot_mode_settings.html>
-;;;
-;;; Code:
-
 (define visionfive2-barebones-os
   (operating-system
     (host-name "visionfive2")
diff --git a/gnu/system/install.scm b/gnu/system/install.scm
index 2f5d5d4b1c9..80f5a51fdae 100644
--- a/gnu/system/install.scm
+++ b/gnu/system/install.scm
@@ -24,6 +24,13 @@
 ;;; You should have received a copy of the GNU General Public License
 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+;;;
+;;; This module provides an 'operating-system' definition for use on images
+;;; for USB sticks etc., for the installation of the GNU system.
+;;;
+;;; Code:
+
 (define-module (gnu system install)
   #:use-module ((guix licenses) #:prefix license:)
   #:use-module (gnu)
@@ -88,13 +95,6 @@
             wandboard-installation-os
             os-with-u-boot))
 
-;;; Commentary:
-;;;
-;;; This module provides an 'operating-system' definition for use on images
-;;; for USB sticks etc., for the installation of the GNU system.
-;;;
-;;; Code:
-
 
 ;;;
 ;;; Documentation service.
diff --git a/gnu/system/keyboard.scm b/gnu/system/keyboard.scm
index 5bd13a44be4..672fbcde8c6 100644
--- a/gnu/system/keyboard.scm
+++ b/gnu/system/keyboard.scm
@@ -16,6 +16,14 @@
 ;;; You should have received a copy of the GNU General Public License
 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+;;;
+;;; This module provides a data structure to represent keyboard layouts
+;;; according to the XKB naming and classification (see the 'xkeyboard-config'
+;;; package).
+;;;
+;;; Code:
+
 (define-module (gnu system keyboard)
   #:use-module (guix gexp)
   #:use-module ((gnu packages xorg)
@@ -31,14 +39,6 @@
 
             keyboard-layout->console-keymap))
 
-;;; Commentary:
-;;;
-;;; This module provides a data structure to represent keyboard layouts
-;;; according to the XKB naming and classification (see the 'xkeyboard-config'
-;;; package).
-;;;
-;;; Code:
-
 (define-immutable-record-type <keyboard-layout>
   (%keyboard-layout name variant model options)
   keyboard-layout?
diff --git a/gnu/system/linux-initrd.scm b/gnu/system/linux-initrd.scm
index b56e6cf5d42..4ea0a59e935 100644
--- a/gnu/system/linux-initrd.scm
+++ b/gnu/system/linux-initrd.scm
@@ -20,6 +20,13 @@
 ;;; You should have received a copy of the GNU General Public License
 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+;;;
+;;; Tools to build initial RAM disks (initrd's) for Linux-Libre, and in
+;;; particular initrd's that run Guile.
+;;;
+;;; Code:
+
 (define-module (gnu system linux-initrd)
   #:use-module (guix deprecation)
   #:use-module (guix gexp)
@@ -56,14 +63,6 @@
             base-initrd))
 
 
-;;; Commentary:
-;;;
-;;; Tools to build initial RAM disks (initrd's) for Linux-Libre, and in
-;;; particular initrd's that run Guile.
-;;;
-;;; Code:
-
-
 (define* (expression->initrd exp
                              #:key
                              (guile %guile-static-initrd)
diff --git a/gnu/system/locale.scm b/gnu/system/locale.scm
index 37f6456e673..866e198b2f6 100644
--- a/gnu/system/locale.scm
+++ b/gnu/system/locale.scm
@@ -18,6 +18,12 @@
 ;;; You should have received a copy of the GNU General Public License
 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+;;;
+;;; Locale definitions, and compilation thereof.
+;;;
+;;; Code:
+
 (define-module (gnu system locale)
   #:use-module (guix gexp)
   #:use-module (guix store)
@@ -43,12 +49,6 @@
 
             glibc-supported-locales))
 
-;;; Commentary:
-;;;
-;;; Locale definitions, and compilation thereof.
-;;;
-;;; Code:
-
 (define-record-type* <locale-definition> locale-definition
   make-locale-definition
   locale-definition?
diff --git a/gnu/system/mapped-devices.scm b/gnu/system/mapped-devices.scm
index 8c32c3d3d4d..e7bb3eae726 100644
--- a/gnu/system/mapped-devices.scm
+++ b/gnu/system/mapped-devices.scm
@@ -19,6 +19,13 @@
 ;;; You should have received a copy of the GNU General Public License
 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+;;;
+;;; This module supports "device mapping", a concept implemented by Linux's
+;;; device-mapper.
+;;;
+;;; Code:
+
 (define-module (gnu system mapped-devices)
   #:use-module (guix gexp)
   #:use-module (guix records)
@@ -72,13 +79,6 @@
             raid-device-mapping
             lvm-device-mapping))
 
-;;; Commentary:
-;;;
-;;; This module supports "device mapping", a concept implemented by Linux's
-;;; device-mapper.
-;;;
-;;; Code:
-
 (define-record-type* <mapped-device> %mapped-device
   make-mapped-device
   mapped-device?
diff --git a/gnu/system/nss.scm b/gnu/system/nss.scm
index 930f556e5e5..9beadf05cab 100644
--- a/gnu/system/nss.scm
+++ b/gnu/system/nss.scm
@@ -16,6 +16,12 @@
 ;;; You should have received a copy of the GNU General Public License
 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+;;;
+;;; Bindings for libc's name service switch (NSS) configuration.
+;;;
+;;; Code:
+
 (define-module (gnu system nss)
   #:use-module (rnrs enums)
   #:use-module (guix records)
@@ -38,12 +44,6 @@
 
             name-service-switch->string))
 
-;;; Commentary:
-;;;
-;;; Bindings for libc's name service switch (NSS) configuration.
-;;;
-;;; Code:
-
 (define-record-type* <name-service> name-service
   make-name-service
   name-service?
diff --git a/gnu/system/pam.scm b/gnu/system/pam.scm
index 83cf74d58ce..935419544a8 100644
--- a/gnu/system/pam.scm
+++ b/gnu/system/pam.scm
@@ -17,6 +17,12 @@
 ;;; You should have received a copy of the GNU General Public License
 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+;;;
+;;; Configuration of the pluggable authentication modules (PAM).
+;;;
+;;; Code:
+
 (define-module (gnu system pam)
   #:use-module (guix records)
   #:use-module (guix derivations)
@@ -69,12 +75,6 @@
             pam-root-service-type
             pam-root-service))
 
-;;; Commentary:
-;;;
-;;; Configuration of the pluggable authentication modules (PAM).
-;;;
-;;; Code:
-
 ;; PAM services (see
 ;; <http://www.linux-pam.org/Linux-PAM-html/sag-configuration-file.html>.)
 (define-record-type* <pam-service> pam-service
diff --git a/gnu/system/privilege.scm b/gnu/system/privilege.scm
index fe6e60ad7c4..26d9b2fe289 100644
--- a/gnu/system/privilege.scm
+++ b/gnu/system/privilege.scm
@@ -17,6 +17,14 @@
 ;;; You should have received a copy of the GNU General Public License
 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+;;;
+;;; Data structures representing privileged programs: binaries with additional
+;;; permissions such as setuid/setgid, or POSIX capabilities.  This is meant to
+;;; be used both on the host side and at run time--e.g., in activation snippets.
+;;;
+;;; Code:
+
 (define-module (gnu system privilege)
   #:use-module (guix records)
   #:export (privileged-program
@@ -30,14 +38,6 @@
 
             file-like->setuid-program))
 
-;;; Commentary:
-;;;
-;;; Data structures representing privileged programs: binaries with additional
-;;; permissions such as setuid/setgid, or POSIX capabilities.  This is meant to
-;;; be used both on the host side and at run time--e.g., in activation snippets.
-;;;
-;;; Code:
-
 (define-record-type* <privileged-program>
   privileged-program make-privileged-program
   privileged-program?
diff --git a/gnu/system/setuid.scm b/gnu/system/setuid.scm
index 097797ce8d7..dab31dad5d2 100644
--- a/gnu/system/setuid.scm
+++ b/gnu/system/setuid.scm
@@ -17,6 +17,14 @@
 ;;; You should have received a copy of the GNU General Public License
 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+;;;
+;;; Do not use this module in new code.  It used to define data structures
+;;; representing setuid/setgid programs, but is now a mere compatibility shim
+;;; wrapping a subset of (gnu system privilege).
+;;;
+;;; Code:
+
 (define-module (gnu system setuid)
   #:use-module (gnu system privilege)
   #:use-module (ice-9 match)
@@ -30,14 +38,6 @@
             setuid-program-user
             setuid-program-group))
 
-;;; Commentary:
-;;;
-;;; Do not use this module in new code.  It used to define data structures
-;;; representing setuid/setgid programs, but is now a mere compatibility shim
-;;; wrapping a subset of (gnu system privilege).
-;;;
-;;; Code:
-
 (define-syntax setuid-program
   (lambda (fields)
     (syntax-case fields ()
diff --git a/gnu/system/shadow.scm b/gnu/system/shadow.scm
index f864a4f692e..2cce6e828f6 100644
--- a/gnu/system/shadow.scm
+++ b/gnu/system/shadow.scm
@@ -21,6 +21,12 @@
 ;;; You should have received a copy of the GNU General Public License
 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+;;;
+;;; Utilities for configuring the Shadow tool suite ('login', 'passwd', etc.)
+;;;
+;;; Code:
+
 (define-module (gnu system shadow)
   #:use-module ((guix diagnostics) #:select (formatted-message))
   #:use-module (guix records)
@@ -97,12 +103,6 @@
 
             subids-service-type))
 
-;;; Commentary:
-;;;
-;;; Utilities for configuring the Shadow tool suite ('login', 'passwd', etc.)
-;;;
-;;; Code:
-
 ;; Change the default shell used by new <user-account> records.
 (default-shell (file-append bash "/bin/bash"))
 
diff --git a/gnu/system/vm.scm b/gnu/system/vm.scm
index a6a05862a5c..c4fc3e84745 100644
--- a/gnu/system/vm.scm
+++ b/gnu/system/vm.scm
@@ -22,6 +22,12 @@
 ;;; You should have received a copy of the GNU General Public License
 ;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+;;;
+;;; Tools to evaluate build expressions within virtual machines.
+;;;
+;;; Code:
+
 (define-module (gnu system vm)
   #:use-module (guix config)
   #:use-module (guix store)
@@ -91,12 +97,6 @@
             common-qemu-options))
 
 
-;;; Commentary:
-;;;
-;;; Tools to evaluate build expressions within virtual machines.
-;;;
-;;; Code:
-
 ;; By default, the msize value is 8 KiB, which according to QEMU is
 ;; insufficient and would degrade performance.  The msize value should roughly
 ;; match the bandwidth of the system's IO (see: