systemd: rewrite comments

In order to be more readable and fit the the 80-column limit.

pkgs/os-specific/linux/systemd/default.nix

@@ -68,16 +68,17 @@
 , libpwquality
 , qrencode
 
-  # the (optional) BPF feature requires bpftool, libbpf, clang and llvm-strip to be available during build time.
+  # the (optional) BPF feature requires bpftool, libbpf, clang and llvm-strip to
+  # be available during build time.
   # Only libbpf should be a runtime dependency.
   # Note: llvmPackages is explicitly taken from buildPackages instead of relying
   # on splicing. Splicing will evaluate the adjacent (pkgsHostTarget) llvmPackages
   # which is sometimes problematic: llvmPackages.clang looks at targetPackages.stdenv.cc
-  # which, in the unfortunate case of pkgsCross.ghcjs, `throw`s. If we explicitly
+  # which, in the unfortunate case of pkgsCross.ghcjs, `throw`s. If we
-  # take buildPackages.llvmPackages, this is no problem because
+  # explicitly take buildPackages.llvmPackages, this is no problem because
-  # `buildPackages.targetPackages.stdenv.cc == stdenv.cc` relative to us. Working
+  # `buildPackages.targetPackages.stdenv.cc == stdenv.cc` relative to
-  # around this is important, because systemd is in the dependency closure of
+  # us. Working around this is important, because systemd is in the dependency
-  # GHC via emscripten and jdk.
+  # closure of GHC via emscripten and jdk.
 , bpftools
 , libbpf
 
@@ -93,14 +94,16 @@
     && !stdenv.hostPlatform.isMusl
     # "Unknown 64-bit data model"
     && !stdenv.hostPlatform.isRiscV32
-, withCompression ? true  # adds bzip2, lz4, xz and zstd
+  # adds bzip2, lz4, xz and zstd
+, withCompression ? true
 , withCoredump ? true
 , withCryptsetup ? true
 , withRepart ? true
 , withDocumentation ? true
 , withEfi ? stdenv.hostPlatform.isEfi
 , withFido2 ? true
-, withFirstboot ? false # conflicts with the NixOS /etc management
+  # conflicts with the NixOS /etc management
+, withFirstboot ? false
 , withHomed ? !stdenv.hostPlatform.isMusl
 , withHostnamed ? true
 , withHwdb ? true
@@ -108,8 +111,10 @@
 , withIptables ? true
 , withKmod ? true
 , withLibBPF ? lib.versionAtLeast buildPackages.llvmPackages.clang.version "10.0"
-    && (stdenv.hostPlatform.isAarch -> lib.versionAtLeast stdenv.hostPlatform.parsed.cpu.version "6") # assumes hard floats
+    # assumes hard floats
-    && !stdenv.hostPlatform.isMips64   # see https://github.com/NixOS/nixpkgs/pull/194149#issuecomment-1266642211
+    && (stdenv.hostPlatform.isAarch -> lib.versionAtLeast stdenv.hostPlatform.parsed.cpu.version "6")
+    # see https://github.com/NixOS/nixpkgs/pull/194149#issuecomment-1266642211
+    && !stdenv.hostPlatform.isMips64
     # can't find gnu/stubs-32.h
     && (stdenv.hostPlatform.isPower64 -> stdenv.hostPlatform.isBigEndian)
     # https://reviews.llvm.org/D43106#1019077
@@ -139,7 +144,8 @@
 , withTimedated ? true
 , withTimesyncd ? true
 , withTpm2Tss ? true
-, withUkify ? false  # adds python to closure which is too much by default
+  # adds python to closure which is too much by default
+, withUkify ? false
 , withUserDb ? true
 , withUtmp ? !stdenv.hostPlatform.isMusl
 , withVmspawn ? true
@@ -148,7 +154,7 @@
   # build only libudev and libsystemd
 , buildLibsOnly ? false
 
-  # name argument
+  # yes, pname is an argument here
 , pname ? "systemd"
 
 , libxslt
@@ -171,7 +177,8 @@ let
   wantGcrypt = withResolved || withImportd;
   version = "255.2";
 
-  # Bump this variable on every (major) version change. See below (in the meson options list) for why.
+  # Use the command below to update `releaseTimestamp` on every (major) version
+  # change. More details in the commentary at mesonFlags.
   # command:
   #  $ curl -s https://api.github.com/repos/systemd/systemd/releases/latest | \
   #     jq '.created_at|strptime("%Y-%m-%dT%H:%M:%SZ")|mktime'
@@ -189,11 +196,14 @@ stdenv.mkDerivation (finalAttrs: {
     hash = "sha256-8SfJY/pcH4yrDeJi0GfIUpetTbpMwyswvSu+RSfgqfY=";
   };
 
-  # On major changes, or when otherwise required, you *must* reformat the patches,
+  # On major changes, or when otherwise required, you *must* :
-  # `git am path/to/00*.patch` them into a systemd worktree, rebase to the more recent
+  # 1. reformat the patches,
-  # systemd version, and export the patches again via
+  # 2. `git am path/to/00*.patch` them into a systemd worktree,
-  # `git -c format.signoff=false format-patch v${version} --no-numbered --zero-commit --no-signature`.
+  # 3. rebase to the more recent systemd version,
-  # Use `find . -name "*.patch" | sort` to get an up-to-date listing of all patches
+  # 4. and export the patches again via
+  #   `git -c format.signoff=false format-patch v${version} --no-numbered --zero-commit --no-signature`.
+  # Use `find . -name "*.patch" | sort` to get an up-to-date listing of all
+  # patches
   patches = [
     ./0001-Start-device-units-for-uninitialised-encrypted-devic.patch
     ./0002-Don-t-try-to-unmount-nix-or-nix-store.patch
@@ -261,8 +271,8 @@ stdenv.mkDerivation (finalAttrs: {
       "$out/lib/systemd/boot/efi"
   '' + (
     let
-      # The following patches references to dynamic libraries to ensure that
+      # The following patches references to dynamic libraries to ensure that all
-      # all the features that are implemented via dlopen(3) are available (or
+      # the features that are implemented via dlopen(3) are available (or
       # explicitly deactivated) by pointing dlopen to the absolute store path
       # instead of relying on the linkers runtime lookup code.
       #
@@ -274,11 +284,11 @@ stdenv.mkDerivation (finalAttrs: {
       # found` when using e.g. --grep with journalctl. Those errors should
       # become less unexpected now.
       #
-      # There are generally two classes of dlopen(3) calls. Those that we want to
+      # There are generally two classes of dlopen(3) calls. Those that we want
-      # support and those that should be deactivated / unsupported. This change
+      # to support and those that should be deactivated / unsupported. This
-      # enforces that we handle all dlopen calls explicitly. Meaning: There is
+      # change enforces that we handle all dlopen calls explicitly. Meaning:
-      # not a single dlopen call in the source code tree that we did not
+      # There is not a single dlopen call in the source code tree that we did
-      # explicitly handle.
+      # not explicitly handle.
       #
       # In order to do this we introduced a list of attributes that maps from
       # shared object name to the package that contains them. The package can be
@@ -287,7 +297,8 @@ stdenv.mkDerivation (finalAttrs: {
       # path location).
       #
       # To get a list of dynamically loaded libraries issue something like
-      # `grep -ri '"lib[a-zA-Z0-9-]*\.so[\.0-9a-zA-z]*"'' $src` and update the below list.
+      #   `grep -ri '"lib[a-zA-Z0-9-]*\.so[\.0-9a-zA-z]*"'' $src`
+      # and update the list below.
       dlopenLibs =
         let
           opt = condition: pkg: if condition then pkg else null;
@@ -373,7 +384,8 @@ stdenv.mkDerivation (finalAttrs: {
     # patch all the dlopen calls to contain absolute paths to the libraries
     lib.concatMapStringsSep "\n" patchDlOpen dlopenLibs
   )
-  # finally ensure that there are no left-over dlopen calls (or rather strings pointing to shared libraries) that we didn't handle
+  # finally ensure that there are no left-over dlopen calls (or rather strings
+  # pointing to shared libraries) that we didn't handle
   + ''
     if grep -qr '"lib[a-zA-Z0-9-]*\.so[\.0-9a-zA-z]*"' src; then
       echo "Found unhandled dynamic library calls: "
@@ -460,12 +472,13 @@ stdenv.mkDerivation (finalAttrs: {
   mesonFlags = [
     # Options
 
-    # We bump this variable on every (major) version change to ensure
+    # We bump this attribute on every (major) version change to ensure that we
-    # that we have known-good value for a timestamp that is in the (not so distant) past.
+    # have known-good value for a timestamp that is in the (not so distant)
-    # This serves as a lower bound for valid system timestamps during startup. Systemd will
+    # past. This serves as a lower bound for valid system timestamps during
-    # reset the system timestamp if this date is +- 15 years from the system time.
+    # startup. Systemd will reset the system timestamp if this date is +- 15
+    # years from the system time.
     # See the systemd v250 release notes for further details:
-    # https://github.com/systemd/systemd/blob/60e930fc3e6eb8a36fbc184773119eb8d2f30364/NEWS#L258-L266
+    #   https://github.com/systemd/systemd/blob/60e930fc3e6eb8a36fbc184773119eb8d2f30364/NEWS#L258-L266
     (lib.mesonOption "time-epoch" releaseTimestamp)
 
     (lib.mesonOption "version-tag" version)
@@ -615,8 +628,13 @@ stdenv.mkDerivation (finalAttrs: {
   ];
   preConfigure =
     let
-      # A list of all the runtime binaries that the systemd executables, tests and libraries are referencing in their source code, scripts and unit files.
+      # A list of all the runtime binaries referenced by the source code (plus
-      # As soon as a dependency isn't required anymore we should remove it from the list. The `where` attribute for each of the replacement patterns must be exhaustive. If another (unhandled) case is found in the source code the build fails with an error message.
+      # scripts and unit files) of systemd executables, tests and libraries.
+      # As soon as a dependency is lo longer required we should remove it from
+      # the list.
+      # The `where` attribute for each of the replacement patterns must be
+      # exhaustive. If another (unhandled) case is found in the source code the
+      # build fails with an error message.
       binaryReplacements = [
         { search = "/usr/bin/getent"; replacement = "${getent}/bin/getent"; where = [ "src/nspawn/nspawn-setuid.c" ]; }
 
@@ -777,11 +795,11 @@ stdenv.mkDerivation (finalAttrs: {
     mv $out/lib/sysusers.d $out/example
   '';
 
-  # Avoid *.EFI binary stripping. At least on aarch64-linux strip
+  # Avoid *.EFI binary stripping.
-  # removes too much from PE32+ files:
+  # At least on aarch64-linux strip removes too much from PE32+ files:
   #   https://github.com/NixOS/nixpkgs/issues/169693
-  # The hack is to move EFI file out of lib/ before doStrip
+  # The hack is to move EFI file out of lib/ before doStrip run and return it
-  # run and return it after doStrip run.
+  # after doStrip run.
   preFixup = lib.optionalString withBootloader ''
     mv $out/lib/systemd/boot/efi $out/dont-strip-me
   '';
@@ -806,12 +824,11 @@ stdenv.mkDerivation (finalAttrs: {
     (builtins.map (p: p.__spliced.buildHost or p) finalAttrs.nativeBuildInputs);
 
   passthru = {
-    # The interface version prevents NixOS from switching to an
+    # The `interfaceVersion` attribute below points out the incompatibilities
-    # incompatible systemd at runtime.  (Switching across reboots is
+    # between systemd versions. When the new systemd build is
-    # fine, of course.)  It should be increased whenever systemd changes
+    # backwards-compatible with the previous one, then they can be switched at
-    # in a backwards-incompatible way.  If the interface version of two
+    # runtime (the reboot being optional in this case); otherwise, a reboot is
-    # systemd builds is the same, then we can switch between them at
+    # needed - and therefore `interfaceVersion` should be incremented.
-    # runtime; otherwise we can't and we need to reboot.
     interfaceVersion = 2;
 
     inherit withCryptsetup withHostnamed withImportd withKmod withLocaled withMachined withPortabled withTimedated withUtmp util-linux kmod kbd;