From 3c3e8772c4d66492f459e0a6ccfc35da7bea51bf Mon Sep 17 00:00:00 2001
From: Joel Holdsworth <joel@airwebreathe.org.uk>
Date: Tue, 7 Oct 2025 10:04:18 -0700
Subject: [PATCH] dockerTools: Tidied comments

Co-authored-by: commiterate <111539270+commiterate@users.noreply.github.com>
---
 pkgs/build-support/docker/default.nix | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/pkgs/build-support/docker/default.nix b/pkgs/build-support/docker/default.nix
index 909dc1321b76..2293ccae73f7 100644
--- a/pkgs/build-support/docker/default.nix
+++ b/pkgs/build-support/docker/default.nix
@@ -1241,7 +1241,8 @@ rec {
     result
   );
 
-  # This function streams a docker image that behaves like a nix-shell for a derivation
+  # This function streams a docker image that behaves like a nix-shell for a derivation.
+  #
   # Docs: doc/build-helpers/images/dockertools.section.md
   # Tests: nixos/tests/docker-tools-nix-shell.nix
   streamNixShellImage =
@@ -1357,10 +1358,14 @@ rec {
         binSh
         usrBinEnv
         (fakeNss.override {
-          # Allows programs to look up the build user's home directory
+          # Allows programs to look up the build user's home directory.
+          #
           # https://github.com/NixOS/nix/blob/2.32.0/src/libstore/unix/build/linux-derivation-builder.cc#L409-L416
-          # Slightly differs however: We use the passed-in homeDirectory instead of sandboxBuildDir.
-          # We're doing this because it's arguably a bug in Nix that sandboxBuildDir is used here: https://github.com/NixOS/nix/issues/6379
+          #
+          # This slightly differs, however, since we use the passed-in `homeDirectory` instead of `sandboxBuildDir`.
+          # We're doing this because it is arguably a bug in Nix that `sandboxBuildDir` is used here.
+          #
+          # https://github.com/NixOS/nix/issues/6379
           extraPasswdLines = [
             "nixbld:x:${toString uid}:${toString gid}:Build user:${homeDirectory}:/noshell"
           ];
@@ -1373,12 +1378,11 @@ rec {
       fakeRootCommands = ''
         # Effectively a single-user installation of Nix, giving the user full
         # control over the Nix store. Needed for building the derivation this
-        # shell is for, but also in case one wants to use Nix inside the
-        # image
+        # shell is for, but also in case one wants to use Nix inside the image.
         mkdir -p ./nix/{store,var/nix} ./etc/nix
         chown -R ${toString uid}:${toString gid} ./nix ./etc/nix
 
-        # Gives the user control over the build directory
+        # Gives the user control over the build directory.
         mkdir -p .${sandboxBuildDir}
         chown -R ${toString uid}:${toString gid} .${sandboxBuildDir}
       '';
@@ -1403,7 +1407,8 @@ rec {
       config.Env = lib.mapAttrsToList (name: value: "${name}=${value}") envVars;
     };
 
-  # Wrapper around streamNixShellImage to build an image from the result
+  # Wrapper around `streamNixShellImage` to build an image from the result.
+  #
   # Docs: doc/build-helpers/images/dockertools.section.md
   # Tests: nixos/tests/docker-tools-nix-shell.nix
   buildNixShellImage =